Create Order
Direct order submission allows channels to submit fully composed orders, including their own tax and shipping calculations, in a single request to the merchant through Violet. This feature overrides the platform’s built-in pricing engine, ensuring accuracy in the merchant’s system of record and customer communications.
Learn more about Direct Order Submission in this guide.
The following information is required to be included in the Order payload of this request:
- First Name
- Last Name
- Shipping Address
- Bag(s)
For a multi-merchant Order, multiple bags must be created in the Order payload. Each Bag must contain items from only one merchant and have its own shipping method.
Violet currently only supports accepting Single-use Stripe Tokens as a payment method in this endpoint.
Body
Violet Order Entity
App Customer ID. This should be used to map the order to the ID of the customer in your application.
ID of the App responsible for the creation and submission of this Order.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
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.
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.
ID of the App responsible for the creation and submission of this Order.
ID of the merchant the Bag is related to.
ID of the parent order the Bag is a child of.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
Optional ID of the Order in the channels system. Automatically obtained through the app_order_id applied to the Order.
IN_PROGRESS, SUBMITTED, ACCEPTED, COMPLETED, PARTIALLY_REFUNDED, REFUNDED, REJECTED, CANCELED, BACKORDERED The type of Channel that originated this Bag.
APP, MARKETPLACE, FACEBOOK, INSTAGRAM, WALMART, GOOGLE, TIKTOK, SNAPCHAT, PINTEREST The rate used to calculate the apps commission rate for the Bag.
Base currency of the Bag.
Exchange rate of currency and external currency, if different, at the time the Bag was last priced.
Date the Bag was created in Violet.
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.
Date the Bag was last modified in Violet.
The total discounts applied to the price of the Bag in the base currency. In Cents
A list of discounts, if any, that have been applied to this Bag.
Amount of discount
Total amount of discount applied to bag
ID of the Bag this discount belong to
Code of discount
Date of creation
Date of last bag discount update
Customer email address, possibly necessary for once-per-customer discounts.
External ID of discount
Percentage of discount
Status of discount
PENDING, APPLIED, INVALID, NOT_SUPPORTED, ERROR, EXPIRED Target type of the discount
ORDER, SKU, SHIPPING Type of discount
CODE Value type of discount
AMOUNT, PERCENTAGE Dispute status of the Bag.
UNDISPUTED, IN_DISPUTE, DISPUTE_WON, DISPUTE_LOST If the Bag is attached to an external cart in the commerce platform.
Currency of the equivalent cart on external commerce platform.
ID of the Order on the external commerce platform. This value will be null until the Order submitted.
Financial status of the Bag.
UNPAID, AUTHORIZED, PENDING, PAID, PARTIALLY_PAID, REFUNDED, PARTIALLY_REFUNDED, VOIDED Fulfillment status of the Bag.
PROCESSING, SHIPPED, PARTIALLY_SHIPPED, DELIVERED, COULD_NOT_DELIVER, RETURNED A list of fulfillments, if any, that have been applied to this Bag.
ID of the bag the fulfillment belongs to.
Carrier responsible for the fulfillment. Will be OTHER if raw carrier is not recognized.
OTHER, UPS, USPS, FEDEX, DHL, ONTRAC, ROYAL_MAIL, SENDLE, POSTNORD Status provided by the carrier.
PENDING, LABEL_PURCHASED, LABEL_PRINTED, CONFIRMED, READY_FOR_PICKUP, IN_TRANSIT, OUT_FOR_DELIVERY, ATTEMPTED_DELIVERY, DELIVERED, FAILURE, NONE_PROVIDED ID of the fulfillment on the external commerce platform.
Raw name of carrier from the external commerce platform.
SKUs fulfilled by this fulfillment.
Status of the bag fullfillment.
PENDING, PROCESSING, SUCCESS, CANCELED, ERROR, FAILURE, NONE_PROVIDED Tracking number provided by the carrier.
Tracking URL provided by the carrier.
Name of the merchant the Bag is related to.
The commerce platform used by this merchant.
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 Date when the Bag can no longer be refunded.
Shipping Methods belonging to an Order
ID of the Bag the Shipping Method applies to
ID of the merchant the bag belongs to
Total cost of the Shipping Method. In Cents
ID of the referenced Shipping Method
OTHER, UPS, USPS, FEDEX, DHL, ONTRAC, ROYAL_MAIL, SENDLE, POSTNORD Is the shipping method custom. True when the price has been overridden.
ID(s) on external ecommerce platform
Shipping Method Label
Maximum Subtotal. In Cents. Only applies to Flat Rate by Price
Maximum Weight. In Cents. Only applies to Flat Rate by Weight
Minimum Subtotal. In Cents. Only applies to Flat Rate by Price
Minimum Weight. In Cents. Only applies to Flat Rate by Weight
Carrier Tracking Number
Type of Shipping Method
CALCULATED, FLAT_RATE_PRICE, FLAT_RATE_WEIGHT The sum of all shipping methods applied to the Bag in the base currency. In Cents
Sku's (line items) that have been added to the Bag.
ID of the referenced Sku from the Violet catalog.
ID of the App responsible for the creation and submission of this Order.
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.
Name of the brand selling this Sku.
Is the Sku custom. Is true when the price has been overridden.
Used to provide the merchant with custom values for the product. This functionality is currently limited to Shopify merchants.
ID of the SKU on the external commerce platform.
Height of Sku.
Unique ID of the Sku in relation to the order.
Length of Sku.
Price of the Sku multiplied by the quantity, in Cents
ID of the Merchant this Sku belongs to.
Name of the Sku, as provided by the merchant.
ID of the parent Offer that this Sku is a child of.
Price of the individual SKU, in cents.
ID of the parent product the offer is a child off.
Product type that describes the Sku.
PHYSICAL, DIGITAL, VIRTUAL, BUNDLED Quantity of the Sku being purchased. Quantities over 1000 will default to 1000.
x < 1000The quantity of this item that has been fulfilled by the merchant.
Rates that apply specifically to this Sku such as taxes, fees, or duties.
Total Tax amount on Bag. In Cents
Rate Name
ID of the Order SKU the Rate belongs to
Rate Type
TAX, SHIPPING, FEE, DUTY Rate
Current status of the Sku.
IN_PROGRESS, PROCESSING, SHIPPED, PARTIALLY_SHIPPED, DELIVERED, COULD_NOT_DELIVER, RETURNED, CANCELED, REFUNDED, ERROR, PARTIALLY_RETURNED, PARTIALLY_REFUNDED URL of the thumbnail image. Useful for order overview displays.
Weight of Sku.
Width of Sku.
Overall status of the Bag.
IN_PROGRESS, SUBMITTED, ACCEPTED, COMPLETED, PARTIALLY_REFUNDED, REFUNDED, REJECTED, CANCELED, BACKORDERED The price of the Bag in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all the taxes applied to the Bag in the base currency. In Cents
Tax rates applied to the Bag.
Total Tax amount on Bag. In Cents
ID of the Merchant the Bag belongs to
ID of the Order the Tax belongs to
Tax Rate
State abbreviation
Description of the Tax
255Postal/Zip Code
SKUs covered by the Tax
Are taxes included in the cart subtotal. When true the taxes will not be summed separately.
The sum of all item prices, discounts, shipping, and taxes applied to the Bag in the base currency. In Cents
Is this Bag going to be placed through wallet-based checkout.
The shipping or billing address of a user placing an order
First line of the Address
City
Country ISO2 Code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
State or province abbreviated code.
Address Type
SHIPPING, BILLING Second line of the address
Email Address
Name on Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
Base currency of cart
Symbol representing the currency the Order operates in.
Details of the customer placing the order.
Customer's valid email address.
Customer's first name.
Customer's last name.
The shipping or billing address of a user placing an order
First line of the Address
City
Country ISO2 Code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
State or province abbreviated code.
Address Type
SHIPPING, BILLING Second line of the address
Email Address
Name on Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
ID of the Customer on the External Platform
When only one address is provided, should the one address be used for both the shipping and billing addresses.
The shipping or billing address of a user placing an order
First line of the Address
City
Country ISO2 Code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
State or province abbreviated code.
Address Type
SHIPPING, BILLING Second line of the address
Email Address
Name on Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
ID of the Developer responsible for the creation and submission of this Order.
The total discounts applied to the price of the Order in the base currency. In Cents.
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.
ID of the parent Bag this error occurred in.
Date the error was first created in Violet.
ID of the entity that caused the error. See the entity_type property to determine which entity this ID is associated with.
Type of entity that caused the error. See the entity_id property to determine which entity of this type is related to the error.
ORDER, BAG, SKU A string message providing more details about the error.
255ID of the parent Order this error occurred in.
The external commerce platform the error occurred in.
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 Type of error, indicates which action was being taken when the error occurred.
EXTERNAL_CREATE_CART, EXTERNAL_ADD_ITEM, EXTERNAL_UPDATE_ITEM, EXTERNAL_REMOVE_ITEM, EXTERNAL_ADD_CUSTOMER, EXTERNAL_ADD_ADDRESSES, EXTERNAL_ADD_SHIPPING_ADDRESS, EXTERNAL_ADD_BILLING_ADDRESS, EXTERNAL_GET_SHIPPING_METHODS, EXTERNAL_SET_SHIPPING_METHOD, EXTERNAL_SET_PAYMENT_METHOD, EXTERNAL_PRICE_CART, EXTERNAL_SUBMIT_CART, INTERNAL_ADD_ITEM, EXTERNAL_DELETE_CART, EXTERNAL_CANCEL_ORDER, EXTERNAL_WRITE_ORDER, EXTERNAL_MARK_ORDER_AS_PAID, EXTERNAL_ADD_DISCOUNT_CODE, EXTERNAL_REMOVE_DISCOUNT_CODE, EXTERNAL_DELETE_ORDER, EXTERNAL_REFUND_ORDER Boolean indicating if the cart/order will be payed using a payment intent.
IN_PROGRESS, PROCESSING, COMPLETED, CANCELED, PARTIALLY_REFUNDED, REFUNDED, REQUIRES_ACTION Payment intent client secret. Use for payment intent based payment capture and external captures
Payment Method belonging to an Order
ID of the referenced Payment Method
Brand of Card
Name as it appears on Card
Is Default Method
Card Expiration Month
Card Expiration Year
Last Four Numbers on Card
Payment Transactions associated to the bags on this Cart
Amount of this payment in the fractional currency unit of this transaction (e.g. cents). This is the amount charged to the shopper.
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.
Identifier of the Order entity that this payment transaction is associated with
Payment Provider that this transaction is executed against. This is the provider that handles payment processing for this transaction.
Identifier of the payment transaction in the underlying payment provider system.
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.
AUTOMATIC, CUSTOM, EXTERNAL 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.
PROCESSING, CAPTURED, CANCELLED, FAILED, BYPASSED, REQUIRES_ACTION, REQUIRES_PAYMENT_METHOD, REQUIRES_AUTHORIZATION, AUTHORIZED, REFUNDED, PARTIALLY_REFUNDED Time at which the object was created. In ISO-8601 format.
Time at which the object was last modified. In ISO-8601 format.
List of errors associated to this payment transaction during processing.. This value will only be populated if there are errors during processing
Error message describing the issue in the underlying system.
Identifier of the PaymentTransaction entity that this error is associated with
Unique error code corresponding to this error.
Unique identifier for the object
Metadata from the payment provider associated to this payment transaction
Metadata from the payment provider associated to this payment transaction
Client secret for the payment intent associated to this payment transaction
Identifier of the payment method associated with this payment transaction in Violet.
Identifier of the payment method associated with this payment transaction in the underlying payment provider system.
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.
PROCESSING, CAPTURED, CANCELLED, FAILED, BYPASSED, REQUIRES_ACTION, REQUIRES_PAYMENT_METHOD, REQUIRES_AUTHORIZATION, AUTHORIZED, REFUNDED, PARTIALLY_REFUNDED 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.
AUTOMATIC, CUSTOM, EXTERNAL Status of the transfer of distributions associated with this payment transaction.
SENT, REVERSED, PARTIALLY_REVERSED, PENDING, FAILED, BYPASSED 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.
The shipping or billing address of a user placing an order
First line of the Address
City
Country ISO2 Code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
State or province abbreviated code.
Address Type
SHIPPING, BILLING Second line of the address
Email Address
Name on Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
The sum of all shipping methods applied to the Order in the base currency. In Cents.
Stripe publishable key. Use for tokenizing payment methods.
The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all the taxes applied to the Order in the base currency. In Cents.
The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.
ID of the User placing the order
Is this cart going to be placed through wallet-based checkout
The payment method request for a cart. If the token is provided no card data is required.
Map the order in Violet to an order record within your system.
CVC code on the credit or debit card.
Expiration month of the credit or debit card.
Expiration year of the credit or debit card.
Number on the credit or debit card.
Postal Code of the credit or debit card.
Submit cart immediately after applying the payment method. Cannot be combined with intent_based_checkout.
Unique identifier of the Customer in the payment provider that the payment method is associated to. When a customer_id is provided, payment_provider must also be specified in the request.
Trigger payment intent based capture
IP address of the device from which this Payment Method originates.
Payment provider that this payment method was created on, if any.
Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.
Type of the payment method being passed in.
SINGLE_USE_CARD_TOKEN, MULTI_USE_CARD_TOKEN, BANK_TOKEN, PAYMENT_INTENT, VIOLET_PAYMENT_METHOD_ID Response
The response is of type any.
Was this page helpful?