Create Cart

POST

checkout

cart

Header

Query

Body

object

base_currency

string

skus

array

referral_id

string

app_order_id

string

customer

object

user_id

integer

first_name

string

last_name

string

external_id

string

shipping_address

object

name

string

city

string

state

string

country

string

postal_code

string

phone

string

type

enum<string>

string

first_name

string

last_name

string

address_1

string

address_2

string

billing_address

object

name

string

city

string

state

string

country

string

postal_code

string

phone

string

type

enum<string>

string

first_name

string

last_name

string

address_1

string

address_2

string

same_address

boolean

name

string

discounts

array

wallet_based_checkout

boolean

curl --request POST \
  --url https://sandbox-api.violet.io/v1/checkout/cart \
  --header 'Content-Type: application/json' \
  --data '{
  "base_currency": "<string>",
  "skus": [
    {
      "id": 123,
      "merchant_id": 123,
      "app_id": 123,
      "product_id": "<string>",
      "sku_id": 123,
      "external_id": "<string>",
      "name": "<string>",
      "brand": "<string>",
      "thumbnail": "<string>",
      "quantity": 123,
      "price": 123,
      "weight": 123,
      "height": 123,
      "width": 123,
      "length": 123,
      "available": true,
      "status": "IN_PROGRESS",
      "product_type": "PHYSICAL",
      "quantity_fulfilled": 123,
      "order_sku_rates": [],
      "transient_external_product_id": "<string>"
    }
  ],
  "referral_id": "<string>",
  "app_order_id": "<string>",
  "customer": {
    "user_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "external_id": "<string>",
    "shipping_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "billing_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "same_address": true,
    "name": "<string>"
  },
  "discounts": [
    {
      "code": "<string>",
      "merchant_id": 123
    }
  ],
  "wallet_based_checkout": true
}'

{
  "id": 123,
  "token": "<string>",
  "user_id": 123,
  "app_id": 123,
  "developer_id": 123,
  "customer": {
    "user_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "external_id": "<string>",
    "shipping_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "billing_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "same_address": true,
    "name": "<string>"
  },
  "bags": [
    {
      "id": 123,
      "order_id": 123,
      "merchant_id": 123,
      "app_id": 123,
      "external_id": "<string>",
      "status": "IN_PROGRESS",
      "fulfillment_status": "PROCESSING",
      "financial_status": "UNPAID",
      "skus": [],
      "shipping_method": {
        "price": 123,
        "shipping_method_id": "<string>",
        "bag_id": 123,
        "merchant_id": 123
      },
      "taxes": [],
      "sub_total": 123,
      "shipping_total": 123,
      "tax_total": 123,
      "discount_total": 123,
      "total": 123,
      "taxes_included": true,
      "transactions": [],
      "external_checkout": true,
      "commission_rate": 123,
      "date_created": "2023-11-07T05:31:56Z",
      "remorse_period_ends": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "external_currency": "<string>",
      "currency_exchange_rate": 123,
      "channel": "APP",
      "app_order_id": "<string>",
      "platform": "OTHER",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": true,
      "app_name": "<string>",
      "bag_id": 123,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "<string>"
    }
  ],
  "shipping_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "shipping",
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "address_1": "<string>",
    "address_2": "<string>"
  },
  "billing_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "shipping",
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "address_1": "<string>",
    "address_2": "<string>"
  },
  "payment_method": {
    "brand": "<string>",
    "last_four": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cardholder_name": "<string>",
    "payment_method_id": 123,
    "default": true
  },
  "sub_total": 123,
  "shipping_total": 123,
  "tax_total": 123,
  "discount_total": 123,
  "total": 123,
  "app_customer_id": "<string>",
  "app_order_id": "<string>",
  "status": "in_progress",
  "is_guest": true,
  "date_created": "2023-11-07T05:31:56Z",
  "date_last_modified": "2023-11-07T05:31:56Z",
  "priced": true,
  "wallet_based_checkout": true,
  "currency": "<string>",
  "referral_id": "<string>",
  "errors": [
    {
      "id": 123,
      "order_id": 123,
      "bag_id": 123,
      "entity_id": "<string>",
      "type": "EXTERNAL_CREATE_CART",
      "message": "<string>",
      "date_created": "2023-11-07T05:31:56Z",
      "platform": "OTHER"
    }
  ],
  "currency_symbol": "<string>",
  "app_name": "<string>",
  "stripe_key": "<string>",
  "payment_intent_client_secret": "<string>",
  "guest": true,
  "order_status": "IN_PROGRESS",
  "intent_based_checkout": true,
  "order_id": 123
}

Note: For more details on this endpoint please refer to the the API Reference

Cart creation begins the checkout process. Products can be added to the cart at creation with a JSON Body listing 1 or more sku_id & quantity pairs.

It is not required that you add a SKU to create a cart, since it is possible for your customers cart to be empty, however, in this example, we will purchase a product with the SKU 10064 (which we noted down from the previous section)

Headers

X-Violet-Token

string

X-Violet-App-Secret

string

X-Violet-App-Id

integer

Query Parameters

apply_current_user

boolean

default: false

default_payment

boolean

default: false

app_order_id

string

base_currency

string

referral_id

string

channel

enum<string>

Available options:

APP,

MARKETPLACE,

FACEBOOK,

INSTAGRAM,

WALMART,

GOOGLE,

TIKTOK,

SNAPCHAT,

PINTEREST

async

boolean

default: true

Body

application/json

base_currency

string

Base currency of cart

skus

object[]

Optional collection of SKUs

referral_id

string

Associate the order with a user or affiliate in your system

app_order_id

string

Map the order in Violet to an order record within your system

customer

object

The Customer Placing the Order

discounts

object[]

Optional collection of Discounts

wallet_based_checkout

boolean

Boolean denoting whether or not this order will be placed through a wallet based payment mechanism such as apple pay

Response

200 - application/json

integer

token

string

user_id

integer

ID of the User placing the order

app_id

integer

ID of the App creating the order

developer_id

integer

ID of the Developer who placed

customer

object

The Customer Placing the Order

bags

object[]

Bags in the Order

bags.id

integer

bags.order_id

integer

required

ID of the Order the Bag belongs to

bags.merchant_id

integer

required

ID of the Merchant the Bag references

bags.app_id

integer

required

ID of the App creating this Bag

bags.external_id

string

ID of the Order on the External Ecommerce Platform

bags.status

enum<string>

Status

Available options:

IN_PROGRESS,

SUBMITTED,

ACCEPTED,

COMPLETED,

PARTIALLY_REFUNDED,

REFUNDED,

REJECTED,

CANCELED,

BACKORDERD

bags.fulfillment_status

enum<string>

Fulfillment Status

Available options:

PROCESSING,

SHIPPED,

PARTIALLY_SHIPPED,

DELIVERED,

COULD_NOT_DELIVER,

RETURNED

bags.financial_status

enum<string>

Financial Status

Available options:

UNPAID,

AUTHORIZED,

PENDING,

PAID,

PARTIALLY_PAID,

REFUNDED,

PARTIALLY_REFUNDED,

VOIDED

bags.skus

object[]

SKUs added to the bag

bags.shipping_method

object

required

Shipping Methods belonging to an Order

bags.taxes

object[]

required

Taxes applied to the bag

bags.sub_total

integer

Subtotal of the bag

bags.shipping_total

integer

Shipping Total of the bag

bags.tax_total

integer

Tax Total of the bag

bags.discount_total

integer

Discount Total of the bag

bags.total

integer

Total price of the bag

bags.taxes_included

boolean

Are taxes included in the cart total.

bags.transactions

object[]

Transactions of the bag

bags.external_checkout

boolean

If bag is tracked externally

bags.commission_rate

number

The developer commission rate

bags.date_created

string

Date of creation

bags.remorse_period_ends

string

Date when the bag can no longer be refunded

bags.currency

string

Base currency of cart

bags.external_currency

string

Currency of cart on external ecommerce platform

bags.currency_exchange_rate

number

Exchange rate of currency and external currency, if different, at the time the bag was last priced.

bags.channel

enum<string>

The channel that originated this order.

Available options:

APP,

MARKETPLACE,

FACEBOOK,

INSTAGRAM,

WALMART,

GOOGLE,

TIKTOK,

SNAPCHAT,

PINTEREST

bags.app_order_id

string

App Order ID

bags.platform

enum<string>

The commerce platform used by this merchant.

Available options:

OTHER,

SHOPIFY,

MAGENTO,

MAGENTO_ONE,

WOOCOMMERCE,

BIGCOMMERCE,

LIGHTSPEED,

ECWID,

YAAS,

SPREECOMMERCE,

DEMANDWARE,

VOLUSION,

PRESTASHOP,

THREEDCART,

SYLIUS,

WIX,

SWELL,

MIVA,

WEBSPHERE,

ORACLECC,

SAPCC,

SQUARESPACE,

SHOPWARE,

COMMERCETOOLS,

MEDUSA,

ABICART,

SPRYKER,

MYSTORE,

CENTRA,

XCART,

VTEX,

KIBO,

SALEOR,

VENDO,

DIGITALRIVER,

CUSTOM

bags.fulfillments

object[]

bags.discounts

object[]

bags.wallet_based_checkout

boolean

Is this bag going to be placed through wallet-based checkout

bags.app_name

string

Name of app that originated the order.

bags.bag_id

integer

bags.bag_status

enum<string>

Available options:

IN_PROGRESS,

SUBMITTED,

ACCEPTED,

COMPLETED,

PARTIALLY_REFUNDED,

REFUNDED,

REJECTED,

CANCELED,

BACKORDERED

bags.merchant_name

string

Name of Merchant

shipping_address

object

The shipping or billing address of a user placing an order

billing_address

object

The shipping or billing address of a user placing an order

payment_method

object

Payment Method belonging to an Order

sub_total

integer

Subtotal of the Order

shipping_total

integer

Shipping Total of the Order

tax_total

integer

Tax Total of the Order

discount_total

integer

Discount Total of the Order

total

integer

Total of the Order

app_customer_id

string

App Customer ID

app_order_id

string

App Order ID

status

enum<string>

required

Status of the Order

Available options:

in_progress,

processing,

completed,

canceled,

partially_refunded,

refunded,

requires_action

is_guest

boolean

Order is Guest

date_created

string

Date of order creation

date_last_modified

string

Date of last order update

priced

boolean

Is the cart priced

wallet_based_checkout

boolean

Is this cart going to be placed through wallet-based checkout

currency

string

Base currency of cart

referral_id

string

Optional value used to represent an identifier in your system.

errors

object[]

Errors on the Order

currency_symbol

string

Symbol representing the desired currency

app_name

string

Name of app that originated the order.

stripe_key

string

Stripe publishable key. Use for tokenizing payment methods.

payment_intent_client_secret

string

Payment intent client secret

guest

boolean

order_status

enum<string>

Available options:

IN_PROGRESS,

PROCESSING,

COMPLETED,

CANCELED,

PARTIALLY_REFUNDED,

REFUNDED,

REQUIRES_ACTION

intent_based_checkout

boolean

order_id

integer

Was this page helpful?

Overview Apply Guest Customer to Cart

curl --request POST \
  --url https://sandbox-api.violet.io/v1/checkout/cart \
  --header 'Content-Type: application/json' \
  --data '{
  "base_currency": "<string>",
  "skus": [
    {
      "id": 123,
      "merchant_id": 123,
      "app_id": 123,
      "product_id": "<string>",
      "sku_id": 123,
      "external_id": "<string>",
      "name": "<string>",
      "brand": "<string>",
      "thumbnail": "<string>",
      "quantity": 123,
      "price": 123,
      "weight": 123,
      "height": 123,
      "width": 123,
      "length": 123,
      "available": true,
      "status": "IN_PROGRESS",
      "product_type": "PHYSICAL",
      "quantity_fulfilled": 123,
      "order_sku_rates": [],
      "transient_external_product_id": "<string>"
    }
  ],
  "referral_id": "<string>",
  "app_order_id": "<string>",
  "customer": {
    "user_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "external_id": "<string>",
    "shipping_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "billing_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "same_address": true,
    "name": "<string>"
  },
  "discounts": [
    {
      "code": "<string>",
      "merchant_id": 123
    }
  ],
  "wallet_based_checkout": true
}'

{
  "id": 123,
  "token": "<string>",
  "user_id": 123,
  "app_id": 123,
  "developer_id": 123,
  "customer": {
    "user_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "external_id": "<string>",
    "shipping_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "billing_address": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "type": "shipping",
      "address_1": "<string>"
    },
    "same_address": true,
    "name": "<string>"
  },
  "bags": [
    {
      "id": 123,
      "order_id": 123,
      "merchant_id": 123,
      "app_id": 123,
      "external_id": "<string>",
      "status": "IN_PROGRESS",
      "fulfillment_status": "PROCESSING",
      "financial_status": "UNPAID",
      "skus": [],
      "shipping_method": {
        "price": 123,
        "shipping_method_id": "<string>",
        "bag_id": 123,
        "merchant_id": 123
      },
      "taxes": [],
      "sub_total": 123,
      "shipping_total": 123,
      "tax_total": 123,
      "discount_total": 123,
      "total": 123,
      "taxes_included": true,
      "transactions": [],
      "external_checkout": true,
      "commission_rate": 123,
      "date_created": "2023-11-07T05:31:56Z",
      "remorse_period_ends": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "external_currency": "<string>",
      "currency_exchange_rate": 123,
      "channel": "APP",
      "app_order_id": "<string>",
      "platform": "OTHER",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": true,
      "app_name": "<string>",
      "bag_id": 123,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "<string>"
    }
  ],
  "shipping_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "shipping",
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "address_1": "<string>",
    "address_2": "<string>"
  },
  "billing_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "shipping",
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "address_1": "<string>",
    "address_2": "<string>"
  },
  "payment_method": {
    "brand": "<string>",
    "last_four": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cardholder_name": "<string>",
    "payment_method_id": 123,
    "default": true
  },
  "sub_total": 123,
  "shipping_total": 123,
  "tax_total": 123,
  "discount_total": 123,
  "total": 123,
  "app_customer_id": "<string>",
  "app_order_id": "<string>",
  "status": "in_progress",
  "is_guest": true,
  "date_created": "2023-11-07T05:31:56Z",
  "date_last_modified": "2023-11-07T05:31:56Z",
  "priced": true,
  "wallet_based_checkout": true,
  "currency": "<string>",
  "referral_id": "<string>",
  "errors": [
    {
      "id": 123,
      "order_id": 123,
      "bag_id": 123,
      "entity_id": "<string>",
      "type": "EXTERNAL_CREATE_CART",
      "message": "<string>",
      "date_created": "2023-11-07T05:31:56Z",
      "platform": "OTHER"
    }
  ],
  "currency_symbol": "<string>",
  "app_name": "<string>",
  "stripe_key": "<string>",
  "payment_intent_client_secret": "<string>",
  "guest": true,
  "order_status": "IN_PROGRESS",
  "intent_based_checkout": true,
  "order_id": 123
}

Introduction

Getting Started

Checkout

Violet Connect

Relay

Product Info

Support

Headers

Query Parameters

Body

Response