Carts and Bags

Checkout revolves around the concept of carts. It involves creating, managing, and submitting carts, which ultimately result in an order. The goal of any checkout experience is to complete a cart and generate an order.

With Violet, you can offer a seamless end-to-end checkout experience to your shoppers without redirecting them to another platform. To understand how to integrate cross-platform checkout in Violet, it is important to grasp the key concepts of Carts, Bags, and Orders.

Order ID = Cart ID

In Violet, a Cart refers to an Order that is still in progress. These terms can be used interchangeably, including their ids. An Order will have the same id as the cart had before it was completed. The Cart encapsulates all the data that the shopper gathers for checkout, such as items, addresses, and payment methods.

Multi-Merchant Checkout

A single Cart can include items from multiple Merchants. Each Merchant has its own nested Bag within the cart. In Cart and Order objects, a Bag is essentially the child of a Cart or an Order related to a single merchant. Bag data contains the items, prices, and tax and shipping rates related to items for a single merchant. This Bag is synchronized with the respective Merchant’s platform. Data from all nested Bags within the order are consolidated into the Cart or Order object.

A Cart contains at least one Bag. A sample Order that had successfully been placed through our Sandbox API can be seen below:

{
    "id": 74909,
    "token": "f43a41f11ea34a06a1c247934f038d0f",
    "user_id": 10397,
    "app_id": 10382,
    "developer_id": 10292,
    "customer": {
        "user_id": 10397,
        "first_name": "First",
        "last_name": "Last",
        "email": "first.last@violet.com",
        "name": "First Last"
    },
    "bags": [
        {
            "id": 60593,
            "order_id": 74909,
            "merchant_id": 10189,
            "app_id": 10382,
            "external_id": "5504990708013",
            "status": "ACCEPTED",
            "fulfillment_status": "PROCESSING",
            "financial_status": "PAID",
            "skus": [
                {
                    "id": 79315,
                    "merchant_id": 10189,
                    "app_id": 10382,
                    "product_id": "87f88388d8a44de6b7ea74d1b822926f",
                    "sku_id": 196585,
                    "external_id": "45101059440941",
                    "name": "Pastel Flower Land - Extra-Large / Design Three / Blue",
                    "brand": "The Violet Garden",
                    "thumbnail": "https://cdn.shopify.com/s/files/1/0758/9363/7421/files/wealthy_floral_design_tshirt_with_a_blue_pastel_colour_backgrou_caefa8e2-b19a-4eb7-84a1-1855591d017b.png",
                    "quantity": 1,
                    "price": 3500,
                    "weight": 3.0,
                    "available": true,
                    "status": "PROCESSING",
                    "product_type": "PHYSICAL",
                    "line_price": 3500
                }
            ],
            "shipping_method": {
                "type": "FLAT_RATE_PRICE",
                "carrier": "OTHER",
                "label": "Economy",
                "price": 490,
                "id": 54773,
                "shipping_method_id": "79da7f8d68e18f7616e6841112693fce",
                "bag_id": 60593,
                "merchant_id": 10189
            },
            "taxes": [
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 4.0,
                    "amount": 140,
                    "description": "New York State Tax"
                },
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 4.0,
                    "amount": 20,
                    "description": "New York State Tax"
                },
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 0.375,
                    "amount": 13,
                    "description": "Kings County Tax"
                },
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 0.375,
                    "amount": 2,
                    "description": "Kings County Tax"
                },
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 4.5,
                    "amount": 158,
                    "description": "Brooklyn City Tax"
                },
                {
                    "order_id": 74909,
                    "merchant_id": 10189,
                    "state": "NY",
                    "rate": 4.5,
                    "amount": 22,
                    "description": "Brooklyn City Tax"
                }
            ],
            "sub_total": 3500,
            "shipping_total": 490,
            "tax_total": 355,
            "discount_total": 0,
            "total": 4345,
            "taxes_included": false,
            "transactions": [
                {
                    "id": 25372,
                    "merchant_id": 10189,
                    "app_id": 10382,
                    "order_id": 74909,
                    "bag_id": 60593,
                    "gateway_transaction_id": "pi_3NqLYJK29KDiBVld0KlSwkbr",
                    "gateway": "stripe",
                    "amount": 4345,
                    "currency": "USD",
                    "type": "CAPTURE",
                    "status": "COMPLETED",
                    "date_created": "2023-09-14T19:50:15+0000",
                    "date_last_modified": "2023-09-14T19:50:21+0000"
                }
            ],
            "external_checkout": true,
            "commission_rate": 25.0,
            "date_created": "2023-09-14T19:49:51+0000",
            "remorse_period_ends": "2023-10-14T19:49:51+0000",
            "currency": "USD",
            "external_currency": "USD",
            "channel": "APP",
            "platform": "SHOPIFY",
            "fulfillments": [],
            "discounts": [],
            "wallet_based_checkout": false,
            "bag_id": 60593,
            "bag_status": "ACCEPTED",
            "merchant_name": "the violet garden"
        }
    ],
    "shipping_address": {
        "name": "First Last",
        "city": "Brooklyn",
        "state": "NY",
        "country": "US",
        "postal_code": "11206",
        "phone": "19171111111",
        "type": "SHIPPING",
        "address_1": "123 Brooklyn Street",
        "first_name": "First",
        "last_name": "Last"
    },
    "billing_address": {
        "name": "First Last",
        "city": "Brooklyn",
        "state": "NY",
        "country": "US",
        "postal_code": "11206",
        "phone": "19171111111",
        "type": "SHIPPING",
        "address_1": "123 Brooklyn Street",
        "first_name": "First",
        "last_name": "Last"
    },
    "payment_method": {
        "brand": "amex",
        "last_four": "0005",
        "exp_month": 12,
        "exp_year": 2027,
        "payment_method_id": 15315
    },
    "sub_total": 3500,
    "shipping_total": 490,
    "tax_total": 355,
    "discount_total": 0,
    "total": 4345,
    "status": "COMPLETED",
    "is_guest": true,
    "date_created": "2023-09-14T19:49:51+0000",
    "date_last_modified": "2023-09-14T19:50:20+0000",
    "priced": true,
    "wallet_based_checkout": false,
    "currency": "USD",
    "channel": "APP",
    "currency_symbol": "$",
    "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
    "order_id": 74909,
    "intent_based_checkout": false,
    "guest": true,
    "order_status": "COMPLETED"
}

You can learn more about each of the states that exist for Orders and Bags in the subsequent pages.

Introduction

Getting Started

Checkout

Violet Connect

Relay

Product Info

Support

Order ID = Cart ID

Multi-Merchant Checkout

Introduction

Getting Started

Checkout

Violet Connect

Relay

Product Info

Support

​Order ID = Cart ID

​Multi-Merchant Checkout

Order ID = Cart ID

Multi-Merchant Checkout