Direct Order Submission
Direct order submission enables channels who calculate their own tax and shipping rates to submit fully composed orders in a single request. For most commerce platforms, the prices you provide in the order submission request will override the built-in pricing engine of the platform. This ensure’s that the merchants system of record and automated customer communication (ex. order confirmation emails) remain accurate.
This guide goes through the steps needed to compose an Order and directly submit it to the merchant through Violet.
Retrieve SKUs from the Violet Catalog
Retrieve SKUs you are able to sell through the Violet Catalog APIs
Offer Publishing Status
The parent Offer of each SKU in the Order must be published to your app at the time of Order creation. This can be determined by examining the publishing_status on an Offer and ensuring that it has a value of PUBLISHED.
If the Offer is not published to your app at the time of Order creation the following exception will be returned:
{
"message": "Sku identified by %s is currently not available for purchase due to offer not published.",
"error": "offer_not_published",
"code": 2011
}Capture Shopper Information
Capture Shopper information through your UI elements. At a minimum, you will need the following:
First Name
Last Name
Email
Shipping Address
You will need to submit this information as a part of the Create Order endpoint. Optionally, if "Billing Address" is different to the "Shipping Address", those details can also be added to the request body.
Estimate Cart Prices
Estimate Cart prices using the Estimate Cart endpoint. You will need to input the information that was previously collected from the Shopper.
Discounts
Direct Order Submission supports two different discount mechanisms to give you maximum flexibility in your Checkout strategy:
Synced Discounts (Promo Codes) — Honor merchant-managed promo codes validated against their ecommerce platform
Custom Discounts — Create your own channel-defined discounts with full control over amounts and targeting
Key Features
Target different parts of the Order: Apply discounts at order level, shipping level, or SKU level
Apply amount or percentage-based Discounts: Pass in fixed amount discounts (in fractional currency unit, e.g. cents) or percentage-based discounts (e.g. 15% off)
Preview Discounts using Estimate Cart: Use Estimate Cart to evaluate discount impact before creating orders
Quick Example
Apply a custom 15% discount to an entire order:
Complete Guide
For comprehensive documentation including request/response examples, field explanations, error handling, and best practices, see our dedicated guide:
Direct Order Submission with Discounts
This guide covers:
Synced vs Custom discount types
Estimate Cart and Create Order usage
All targeting options (ORDER/SKU/SHIPPING)
BagDiscount field reference
Validation rules and error scenarios
Supported platforms
Adding a Payment Method
Violet supports accepting two forms of payment method when creating Orders.
Single-use Card Tokens
Pre-authorized Stripe Payment Intents
Creating a Single-use Card Token
Capture Shopper Credit Card information using Stripe JS Elements and create a Stripe Token:
https://docs.stripe.com/js/tokens/create_token?type=cardElement
Alternatively, if you're using a different user input form to collect and store shopper credit card information, you can call the Stripe API directly to create a token
https://docs.stripe.com/api/tokens/create_card?lang=curl
For the token to be accepted during Checkout, you'll need to ensure that its created using the Stripe Public Key that is associated with the same Stripe account being used for payment orchestration. If this is Violet's Account, please reach out to us for this key.
Using a pre-authorized Payment Intent
Create a payment intent with Stripe
Start with creating a payment intent in Stripe using the Payment Intents API. This must be done on the same account you used to onboard with Violet Payments. Ensure that the amount and currency, match that of the Order you will be creating. Additionally, Violet requires that the payment intent is marked for manual capture. For example:
Store the payment intent ID that Stripe returns in the response.
Add a payment method to the Payment Intent
A payment method must be added to the payment intent prior to it being used when creating an Order. To do this, you can use Stripe.js Elements, or the update Payment Intents API.
Alternatively, you can modify the call in the previous step to include a payment method on payment intent create. For example:
Authorize the payment intent
Authorize the payment intent by calling the Confirm Payment Intent API. This ensures that this is not a fraudulent payment method and that there are sufficient funds for this purchase. Alternatively, if Stripe.js Elements were used to capture the shopper payment method, Stripe may have automatically authorized the shopper payment method. Once a payment intent is authorized, its amount cannot change.
Include the payment intent when calling Create Order
When creating an Order using the API below, include the payment intent as a payment method. For example:
Line Item Tax Support
Line item taxes are required when Tax Remittance is enabled for your app. These can be passed using the rates object on each SKU in the Order. If only tax_total is provided at the Bag level, Violet will automatically allocate it across the SKUs in the Bag based on their relative line prices. Our recommendation, however, is it always included it at the SKU level.
Each SKU within a Bag must include one or more rates objects containing:
name
type (must be TAX)
Either rate, amount, or both
The following examples show each of these options:
A complete Create Order request, with line-item taxes, is shown below:
Creating the Order
Call the Violet Create Order endpoint with the information collected above to create an Order:
The following information must be included to create an Order:
First Name
Last Name
Email
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.
If Order submission succeeds, Violet will respond with a completed Cart.
If there are any issues with submission, they will be returned to instead of the Order above. A new payment token will need to be sent with each Create Order request.
Submission Date
At the time of order submission a date_submitted property on the Order and Bag objects will be populated with ISO 8601 datetime values that reflect the submission time. On the Order object this value will capture the last time the Order was submitted to Violet. Each Bag object within the Order object will reflect the last time an attempt was made to submit the Bag to the external commerce platform.
Zero-Dollar ($0) Orders
Violet fully supports $0 orders through Direct Order Submission, enabling scenarios such as fully discounted orders, promotional campaigns, loyalty rewards, or free product samples where products may have zero monetary value while still requiring order processing and fulfillment tracking.
When $0 Orders Occur
A $0 order can occur when:
All SKUs in the order have a price of $0 (e.g., free promotional items)
Discounts fully offset the order subtotal (e.g., 100% discount code)
A combination of discounts brings the total to $0
How Violet Handles $0 Orders
Payment Processing
When the order total equals $0:
No payment method is required — You can omit
payment_methodfrom your Create Order requestPayment authorization is skipped — Violet does not attempt to charge the shopper
The
PaymentTransactionwill have:capture_status:NOT_REQUIREDpayment_provider: Your app name (not a payment provider like Stripe)
Tax Handling
For $0 orders, tax is calculated as follows:
$0 price SKUs — Tax amount and tax rate are automatically set to $0
Zero bag subtotal — When the bag subtotal is $0 (even if individual SKU prices were reduced by discounts), no tax liability exists
This is consistent with standard tax treatment: when the taxable base is $0, there is no tax to collect.
If you are responsible for tax calculation and remittance, ensure your tax provider is configured to handle $0 taxable amounts. Most tax providers will return $0 tax for a $0 taxable base, but verify this behavior in your integration.
Commission Handling
Violet does not apply commission on $0 orders:
When order total is $0 or negative, commission calculation is skipped
No distribution records are created for commission amounts
This prevents negative commission scenarios
Discounts and $0 Orders
Discounts can reduce an order to $0. When using Custom Discounts:
A discount cannot exceed the bag subtotal (you'll receive a validation error)
When a discount equals the subtotal exactly, the order becomes a $0 order
All $0 order behaviors described above apply when discounts bring the total to $0
Order Lifecycle for $0 Orders
$0 orders follow the same lifecycle as regular orders:
Order Status — Progresses through
PROCESSING→COMPLETEDas normalBag Status — Moves through
ACCEPTED→ fulfillment states as the merchant processes the orderFulfillment — Merchants still receive and fulfill $0 orders through their commerce platform
Webhooks — All standard order webhooks are emitted (ORDER_COMPLETED, BAG_FULFILLED, etc.)
Refunds on $0 Orders
If a merchant initiates a refund on a $0 order:
Violet creates a refund record with
status:EXTERNALNo funds are moved since no payment was captured
The
ORDER_REFUNDEDwebhook is still emittedYour system should update order status accordingly but no financial reversal is needed
Best Practices for $0 Orders
Validate pricing upstream — Ensure your pricing logic is correct before submitting to Violet
Track promotional orders — Use
app_order_idto identify promotional or $0 orders in your systemSet appropriate fulfillment expectations — Merchants will still see and fulfill these orders
Monitor for abuse — Implement rate limiting or other controls to prevent abuse of $0 order functionality
Last updated
Was this helpful?