Learn the basics of creating an end-to-end store using Violet for checkout by running a fully-functional sample iOS App in your local environment.

Before you Begin

Ensure you have the following installed on your local environment before running our sample applications.


Some of the terminology used in this guide is specific to Violet. Please refer to these definitions for new concepts that are introduced.

  • Violet NextJS Sample App — This is the sample application you have downloaded, Ultra.
  • Merchant — The store or brand. The gallery is currently powered by PUBLIC merchants, for demo purposes. In your version, this would be powered by private relationships that you build with brands.
  • Offers — A product from a specific merchant. Since multiple brands can sell the same item, Violet lets you interact with Offers. When viewing the gallery of the sample app, you are interacting with Offers.
  • Cart — A Cart with all the items your shopper is trying to purchase. A core feature Violet powers is multi-merchant checkout. A Cart contains multiple bags; each bag contains items from a single merchant.
  • Bags — The gallery shows multiple brands/merchants, all powered through Violet. A core feature Violet powers is multi-merchant checkout. A bag is a collection of items from one single brand/merchant.

Onboarding Guide

Creating an application in Violet

Violet Applications provide you with the necessary credentials and tools to invoke our APIs and build your new system. Violet applications are the entry point to any system built on Violet and manage merchants you’ve connected to.

  1. Sign up at channel.violet.io/signup or login at channel.violet.io/login
  2. Click ‘Create App’
  3. Name your Application
  4. Save your App Id and App Secret

You can read more about Violet applications here

Cloning the repositories from Github

Check out the VioletSwiftDemoApp repository from Github to your local environment. You can access the repository here.

Logging in with Postman or Curl to fetch your refresh token

Fetch your refresh token using the App Id and App Secret you created in the first step through the following command:

curl --location --request POST '<https://sandbox-api.violet.io/v1/login>' \\
--header 'X-Violet-App-Secret: <REPLACE WITH YOUR APP SECRET>' \\
--header 'X-Violet-App-Id: <REPLACE WITH YOUR APP ID>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "username": "<REPLACE WITH YOUR USERNAME>"

Copy this refresh token and save it for later. You will need it to start the sample application.

Starting the Application

Before starting the iOS Demo App, you will need to run the violet-proxy-server. This is to ensure that your client side application (i.e. iOS build) does not expose app secrets.

To run the violet-proxy-server follow this guide: [/getting-started/resources/violet-proxy-server]

Once you have your proxy server running, you can start your iOS application in your local environment.

  1. Navigate to the root directory of the package you cloned.
  2. Open the Demo.xcworkspace file and the Project will load into Xcode
  3. Once all the Swift Package Dependencies update (happens automatically on project opening)
    1. Run the Build command (⌘B)
  4. Once the Build completes,
    1. ensure the violet-proxy-server is running,
      1. https://github.com/violetio/violet-proxy-server
    2. select one the installed Simulator models, such as iPhone 14 Pro as shown below.
    3. Run the Demo App (⌘R). This will start an iPhone simulator that you can use to perform Checkout.

Performing Checkout

This demo app is already wired to Violet’s Catalog and Checkout APIs. You can now perform checkout directly from the website similar to how any of your shoppers would. Products that you are viewing in this gallery are from PUBLIC Violet merchants available in the Violet Test environment (learn more about this here). You can view the Optional Topics section below to learn how to add your own merchants. The section below shows you how checkout works.

Shopper Checkout

Navigate through the gallery, add items to cart, and check out using Shipping and Billing Information — the same way your shoppers would. During checkout, shipping and billing addresses are required. You will need to pass in real shipping addresses to fetch shipping methods for the items you select in this demo app. Here are some sample addresses and credit cards you can use:

Shipping/Billing Address:

200 West Street
New York, NY 10282

Sample Credit Cards:

Number: 4242 4242 4242 4242
Expiry: 11/29
CVC: 111
Zip Code: 12345

(You can access a full list of test cards on <https://stripe.com/docs/testing>)

View Order Information on your Channel Dashboard

When orders are placed through your app, you can see the status of these on your Channel dashboard.


While the sample application may look and feel like a complete store, please keep in mind that there are many additional, application specific features that would be required before this could be shown to real customers.

  1. User and cart state is not managed — If you close the browser or refresh, your cart will be lost and you will need to re-start the checkout process.
  2. App Id and App Secret are stored on local machine — These should never be exposed to the client side. When deploying as a real application, please remember to separate your backend and front-end servers.

Optional Topics

Enabling your logger

There is a Logger that is currently disabled via the option "loggerEnabled": false,

change this to true to enable and see Logger output in the Xcode Console.

Testing on a Physical Device

2 Steps are required for Device testing:

  1. Uncomment the following block of code in Checkout/Checkout/CheckoutApp.swift:

    //        if let initBasePath = InitJson.initData["basePath"] as? String {
    //            VioletAPI.basePath = initBasePath
    //        }
  2. In the init.json file, set "basePath" to the string:


    where <IP_ADDRESS> is the IP Address of your Mac or server running the violet-proxy-server on your local network.