Set Shipping Methods

POST

checkout

cart

{cart_id}

shipping

curl --request POST \
  --url https://sandbox-api.violet.io/v1/checkout/cart/{cart_id}/shipping \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "bag_id": 11111,
    "shipping_method_id": "07d19139fc0f4558687c1900c696f071"
  }
]'

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "super@mar.io",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 22222,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "IN_PROGRESS",
      "fulfillment_status": "PROCESSING",
      "financial_status": "UNPAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "thumbnail": "https://res.cloudinary.com/violet/image/upload/c_thumb,w_200,g_face/v1729220594/product_media/2taesr1g7sciu8agrrtgaafi2dnzzmsv.jpg",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "bag_id": 11111,
        "merchant_id": 10000,
        "label": "Priority Mail",
        "price": 664,
        "custom": false
      },
      "taxes": null,
      "sub_total": 19998,
      "shipping_total": 664,
      "tax_total": 0,
      "discount_total": 0,
      "total": 20662,
      "taxes_included": false,
      "transactions": null,
      "external_checkout": true,
      "commission_rate": 10,
      "date_created": "2017-06-15T01:01:01+0000",
      "date_last_modified": "2017-06-15T01:01:01+0000",
      "remorse_period_ends": "2017-06-15T01:01:01+0000",
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": false,
      "bag_id": 22222,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "Legacy Games"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "payment_method": null,
  "sub_total": 19998,
  "shipping_total": 664,
  "tax_total": 0,
  "discount_total": 0,
  "total": 20662,
  "app_order_id": "00100100",
  "status": "IN_PROGRESS",
  "is_guest": true,
  "date_created": "2017-06-15T01:01:01+0000",
  "date_last_modified": "2017-06-15T01:01:01+0000",
  "priced": true,
  "wallet_based_checkout": false,
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
  "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
  "payment_transactions": null,
  "intent_based_checkout": true,
  "guest": true,
  "order_id": 11111
}

Apply shipping methods to a cart given its cart_id.

Since each merchant has different shipping methods, a shipping method that corresponds to each bag will be required to be applied. The bag_id and shipping_method in the body of the request must match a valid shipping method provided by the respective merchant.

This endpoint will always return a priced cart. That is to say the order totals will be calculated.

Headers

X-Violet-Token

string

X-Violet-App-Secret

string

X-Violet-App-Id

integer

Path Parameters

cart_id

integer

required

Query Parameters

price_cart

boolean

default: true

Body

application/json · object[]

bag_id

integer

The ID of the bag the Shipping Method belongs to

shipping_method_id

string

ID of the Shipping Method

shipping_method_label

string

Label of the Shipping Method

shipping_method_price

integer

Price of the Shipping Method

custom

boolean

Is the shipping method custom. True when the price has been overridden.

Response

200 - application/json

Violet Order Entity

integer

ID of the Violet cart or order.

token

string

deprecated

An alternative UUID that can be used as an ID to reference the cart or order.

errors

array | null

Errors on the Order. During checkout, if there was an error or issue on one of the order's bags, there will be an error added to this list describing the issue. The checkout API will return 200 with the order object in the response even if there was an issue with a bag so you must always check the response for errors in this list to know if there was an issue on the order.

user_id

integer

deprecated

ID of the User placing the order

app_id

integer

ID of the App responsible for the creation and submission of this Order.

developer_id

integer

ID of the Developer responsible for the creation and submission of this Order.

customer

object | null

Details of the customer placing the order.

customer.first_name

string

required

Customer's first name.

customer.last_name

string

required

Customer's last name.

customer.email

string

required

Customer's valid email address.

customer.user_id

integer | null

deprecated

Reference ID of the customer placing the order.

customer.external_id

string | null

ID of the Customer on the External Platform

customer.shipping_address

object | null

The shipping or billing address of a user placing an order

customer.billing_address

object | null

The shipping or billing address of a user placing an order

customer.same_address

boolean

default: false

When only one address is provided, should the one address be used for both the shipping and billing addresses.

customer.name

string

Full name of the customer.

bags

object[]

One or more Bags that make up the Order. Each Bag will contain the Sku's, shipping methods, and totals unique to a merchant. Each merchant in an Order will have their own Bag.

bags.id

integer

Unique ID of the Bag.

bags.order_id

integer

required

ID of the parent order the Bag is a child of.

bags.merchant_id

integer

required

ID of the merchant the Bag is related to.

bags.app_id

integer

required

ID of the App responsible for the creation and submission of this Order.

bags.external_id

string | null

ID of the Order on the external commerce platform. This value will be null until the Order submitted.

bags.status

enum<string>

Overall status of the Bag.

Available options:

IN_PROGRESS,

SUBMITTED,

ACCEPTED,

COMPLETED,

PARTIALLY_REFUNDED,

REFUNDED,

REJECTED,

CANCELED,

BACKORDERED

bags.fulfillment_status

enum<string>

Fulfillment status of the Bag.

Available options:

PROCESSING,

SHIPPED,

PARTIALLY_SHIPPED,

DELIVERED,

COULD_NOT_DELIVER,

RETURNED

bags.financial_status

enum<string>

Financial status of the Bag.

Available options:

UNPAID,

AUTHORIZED,

PENDING,

PAID,

PARTIALLY_PAID,

REFUNDED,

PARTIALLY_REFUNDED,

VOIDED

bags.dispute_status

enum<string>

default: UNDISPUTED

Dispute status of the Bag.

Available options:

UNDISPUTED,

IN_DISPUTE,

DISPUTE_WON,

DISPUTE_LOST

bags.skus

object[]

Sku's (line items) that have been added to the Bag.

bags.skus.id

integer

Unique ID of the Sku in relation to the order.

bags.skus.offer_id

integer

ID of the parent Offer that this Sku is a child of.

bags.skus.merchant_id

integer

ID of the Merchant this Sku belongs to.

bags.skus.app_id

integer

ID of the App responsible for the creation and submission of this Order.

bags.skus.product_id

string

deprecated

ID of the parent product the offer is a child off.

bags.skus.sku_id

integer

required

ID of the referenced Sku from the Violet catalog.

bags.skus.external_id

string

ID of the SKU on the external commerce platform.

bags.skus.name

string

Name of the Sku, as provided by the merchant.

bags.skus.brand

string

Name of the brand selling this Sku.

bags.skus.thumbnail

string

URL of the thumbnail image. Useful for order overview displays.

bags.skus.quantity

integer

Quantity of the Sku being purchased. Quantities over 1000 will default to 1000.

Required range: x < 1000

bags.skus.price

integer

Price of the individual SKU, in cents.

bags.skus.weight

number | null

Weight of Sku.

bags.skus.height

number | null

Height of Sku.

bags.skus.width

number | null

Width of Sku.

bags.skus.length

number | null

Length of Sku.

bags.skus.available

boolean

Is the product still available for purchase. If a Sku becomes unavailable it likely means that the product became out of stock after it was added to the cart. Unavailable Sku's cannot be purchased.

bags.skus.status

enum<string>

Current status of the Sku.

Available options:

IN_PROGRESS,

PROCESSING,

SHIPPED,

PARTIALLY_SHIPPED,

DELIVERED,

COULD_NOT_DELIVER,

RETURNED,

CANCELED,

REFUNDED,

ERROR,

PARTIALLY_RETURNED,

PARTIALLY_REFUNDED

bags.skus.product_type

enum<string>

Product type that describes the Sku.

Available options:

PHYSICAL,

DIGITAL,

VIRTUAL,

BUNDLED

bags.skus.custom

boolean

Is the Sku custom. Is true when the price has been overridden.

bags.skus.custom_properties

array | null

Used to provide the merchant with custom values for the product. This functionality is currently limited to Shopify merchants.

bags.skus.quantity_fulfilled

integer

The quantity of this item that has been fulfilled by the merchant.

bags.skus.rates

object[]

Rates that apply specifically to this Sku such as taxes, fees, or duties.

bags.skus.line_price

integer

Price of the Sku multiplied by the quantity, in Cents

bags.shipping_method

object | null

Shipping Methods belonging to an Order

bags.taxes

array | null

Tax rates applied to the Bag.

bags.sub_total

integer

The price of the Bag in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.

bags.shipping_total

integer

The sum of all shipping methods applied to the Bag in the base currency. In Cents

bags.tax_total

integer

The sum of all the taxes applied to the Bag in the base currency. In Cents

bags.discount_total

integer

The total discounts applied to the price of the Bag in the base currency. In Cents

bags.total

integer

The sum of all item prices, discounts, shipping, and taxes applied to the Bag in the base currency. In Cents

bags.taxes_included

boolean

default: false

Are taxes included in the cart subtotal. When true the taxes will not be summed separately.

bags.external_checkout

boolean

default: true

If the Bag is attached to an external cart in the commerce platform.

bags.commission_rate

number

The rate used to calculate the apps commission rate for the Bag.

bags.date_created

string

Date the Bag was created in Violet.

bags.date_last_modified

string

Date the Bag was last modified in Violet.

bags.date_last_consolidated

string

Date the Bag was last checked for updates. This is a part of Order Parity and is used to discover missed or unsent webhooks from the external commerce platforms.

bags.remorse_period_ends

string

Date when the Bag can no longer be refunded.

bags.currency

string

Base currency of the Bag.

bags.external_currency

string

Currency of the equivalent cart on external commerce platform.

bags.currency_exchange_rate

number | null

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

bags.channel

enum<string>

The type of Channel that originated this Bag.

Available options:

APP,

MARKETPLACE,

FACEBOOK,

INSTAGRAM,

WALMART,

GOOGLE,

TIKTOK,

SNAPCHAT,

PINTEREST

bags.app_order_id

string | null

Optional ID of the Order in the channels system. Automatically obtained through the app_order_id applied to the Order.

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,

CHORD,

DIGITALRIVER,

SQUARE,

AMAZON,

BIGCARTEL,

CUSTOM

bags.fulfillments

array | null

A list of fulfillments, if any, that have been applied to this Bag.

bags.discounts

array | null

A list of discounts, if any, that have been applied to this Bag.

bags.wallet_based_checkout

boolean

default: false

Is this Bag going to be placed through wallet-based checkout.

bags.app_name

string

Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.

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 the merchant the Bag is related to.

shipping_address

object | null

The shipping or billing address of a user placing an order

billing_address

object | null

The shipping or billing address of a user placing an order

payment_method

object | null

Payment Method belonging to an Order

sub_total

integer

default: 0

The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.

shipping_total

integer

default: 0

The sum of all shipping methods applied to the Order in the base currency. In Cents.

tax_total

integer

default: 0

The sum of all the taxes applied to the Order in the base currency. In Cents.

discount_total

integer

default: 0

The total discounts applied to the price of the Order in the base currency. In Cents.

total

integer

default: 0

The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.

app_customer_id

string | null

App Customer ID. This should be used to map the order to the ID of the customer in your application.

app_order_id

string | null

App Order ID. This should be set to a unique identifier in your system. While not enforced unique in Violet's system, it is strongly recommended that unique values are used for each cart to help correlate identifiers between Violet's system and yours.

status

enum<string>

Status of the Order

Available options:

IN_PROGRESS,

PROCESSING,

COMPLETED,

CANCELED,

PARTIALLY_REFUNDED,

REFUNDED,

REQUIRES_ACTION

is_guest

boolean

default: true

Order is Guest

date_created

string

Date of order creation

date_last_modified

string

Date of last order update

priced

boolean

default: false

Is the cart priced

wallet_based_checkout

boolean

default: false

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

currency

string

default: USD

Base currency of cart

referral_id

string | null

Optional value used to represent an identifier in your system. This value is not required to represent a referral. It can represent the ID of anything in your system and can be used to filter order lookup results. Max length of 128 characters.

currency_symbol

string

Symbol representing the currency the Order operates in.

app_name

string

Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.

stripe_key

string

Stripe publishable key. Use for tokenizing payment methods.

payment_intent_client_secret

string

Payment intent client secret. Use for payment intent based payment capture and external captures

payment_transactions

object[]

Payment Transactions associated to the bags on this Cart

payment_transactions.id

integer

Unique identifier for the object

payment_transactions.order_id

integer

required

Identifier of the Order entity that this payment transaction is associated with

payment_transactions.payment_provider

string

required

Payment Provider that this transaction is executed against. This is the provider that handles payment processing for this transaction.

payment_transactions.payment_provider_transaction_id

string

required

Identifier of the payment transaction in the underlying payment provider system.

payment_transactions.payment_method_id

integer

Identifier of the payment method associated with this payment transaction in Violet.

payment_transactions.payment_provider_payment_method_id

string

Identifier of the payment method associated with this payment transaction in the underlying payment provider system.

payment_transactions.payment_intent_client_secret

string

Client secret for the payment intent associated to this payment transaction

payment_transactions.amount

integer

required

Amount of this payment in the fractional currency unit of this transaction (e.g. cents). This is the amount charged to the shopper.

payment_transactions.currency

string

required

Currency that the amount of this payment transaction is reflected in. This is the currency that the payment provider uses to charge the shopper payment method.

payment_transactions.capture_status

enum<string>

Underlying status of the payment capture in the payment provider system and should be used to determine what action to take next against this payment transaction.

Available options:

PROCESSING,

CAPTURED,

CANCELLED,

FAILED,

BYPASSED,

REQUIRES_ACTION,

REQUIRES_PAYMENT_METHOD,

REQUIRES_AUTHORIZATION,

AUTHORIZED,

REFUNDED,

PARTIALLY_REFUNDED

payment_transactions.capture_method

enum<string>

Underlying status of the payment in the payment provider system and should be used to determine what action to take next against this payment transaction.

Available options:

AUTOMATIC,

CUSTOM,

EXTERNAL

payment_transactions.transfer_status

enum<string>

Status of the transfer of distributions associated with this payment transaction.

Available options:

SENT,

REVERSED,

PARTIALLY_REVERSED,

PENDING,

FAILED,

BYPASSED

payment_transactions.transfer_method

enum<string>

Underlying status of the payment in the payment provider system and should be used to determine what action to take next against this payment transaction.

Available options:

AUTOMATIC,

CUSTOM,

EXTERNAL

payment_transactions.metadata

object

Metadata from the payment provider associated to this payment transaction

Identifiers of the Bags in Violet that are associated with this payment transaction. The amount of this payment transaction is directly computed from the total amounts on the related bags.

Identifiers of the Refunds in Violet that are associated with this payment transaction. Refund amounts are not reflected in the amount on this payment transaction.

payment_transactions.errors

object[]

List of errors associated to this payment transaction during processing.. This value will only be populated if there are errors during processing

payment_transactions.date_created

string

Time at which the object was created. In ISO-8601 format.

payment_transactions.date_last_modified

string

Time at which the object was last modified. In ISO-8601 format.

payment_transactions.status

enum<string>

Available options:

PROCESSING,

CAPTURED,

CANCELLED,

FAILED,

BYPASSED,

REQUIRES_ACTION,

REQUIRES_PAYMENT_METHOD,

REQUIRES_AUTHORIZATION,

AUTHORIZED,

REFUNDED,

PARTIALLY_REFUNDED

order_id

integer

guest

boolean

order_status

enum<string>

Available options:

IN_PROGRESS,

PROCESSING,

COMPLETED,

CANCELED,

PARTIALLY_REFUNDED,

REFUNDED,

REQUIRES_ACTION

intent_based_checkout

boolean

Boolean indicating if the cart/order will be payed using a payment intent.

Was this page helpful?

Get Available Shipping Methods Remove Shipping Method

curl --request POST \
  --url https://sandbox-api.violet.io/v1/checkout/cart/{cart_id}/shipping \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "bag_id": 11111,
    "shipping_method_id": "07d19139fc0f4558687c1900c696f071"
  }
]'

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "super@mar.io",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 22222,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "IN_PROGRESS",
      "fulfillment_status": "PROCESSING",
      "financial_status": "UNPAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "thumbnail": "https://res.cloudinary.com/violet/image/upload/c_thumb,w_200,g_face/v1729220594/product_media/2taesr1g7sciu8agrrtgaafi2dnzzmsv.jpg",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "bag_id": 11111,
        "merchant_id": 10000,
        "label": "Priority Mail",
        "price": 664,
        "custom": false
      },
      "taxes": null,
      "sub_total": 19998,
      "shipping_total": 664,
      "tax_total": 0,
      "discount_total": 0,
      "total": 20662,
      "taxes_included": false,
      "transactions": null,
      "external_checkout": true,
      "commission_rate": 10,
      "date_created": "2017-06-15T01:01:01+0000",
      "date_last_modified": "2017-06-15T01:01:01+0000",
      "remorse_period_ends": "2017-06-15T01:01:01+0000",
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": false,
      "bag_id": 22222,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "Legacy Games"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "payment_method": null,
  "sub_total": 19998,
  "shipping_total": 664,
  "tax_total": 0,
  "discount_total": 0,
  "total": 20662,
  "app_order_id": "00100100",
  "status": "IN_PROGRESS",
  "is_guest": true,
  "date_created": "2017-06-15T01:01:01+0000",
  "date_last_modified": "2017-06-15T01:01:01+0000",
  "priced": true,
  "wallet_based_checkout": false,
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
  "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
  "payment_transactions": null,
  "intent_based_checkout": true,
  "guest": true,
  "order_id": 11111
}

Overview

Login

Merchants

Catalog

Orders & Checkout

Events

Apps

Operations

Relay

Ecom Syncs

Headers

Path Parameters

Query Parameters

Body

Response