Checkout

Questions relating to the Checkout API flow.

Is it possible to send metadata in an order object?

While we do support custom properties on an Order Sku, we do not currently support metadata on a top level Order.

Follow our Changelog or reach out on [email protected] for more information.

Can you change the currency of an existing cart?

We don't currently support a shopper changing the currency of their cart after items have been added to a cart. Our suggestion is to create a new cart under the hood with all the same SKUs in the new currency.

What is the referral_id field?

referral_id, is just a string field that is controlled by the channel side. Some Channels have referral id's they want to pass through for merchants. It is okay for this to be null

Can we override prices of an item or shipping value?

Yes line item and shipping method prices can be overridden on several platforms. See Overriding Cart Prices.

Can I access the currency exchange rates being used by Violet?

The real-time exchange rates being utilized by Violet can be accessed through the currencies API.

When a purchase is submitted, what emails does the shopper receive?

Violet does not send any emails to the shopper.

When an order is submitted to the merchants commerce platform, the behavior will typically be the same as if the order had occurred directly on the merchants website. So if a merchant has their store configured to send automated order confirmation emails, and assuming the merchant is provided with the shoppers true email address, the shopper will very likely receive an order confirmation email from the merchant.

How does Violet handle out of stock issues during checkout?

If a shopper tries to add something to a cart, we will return an order error (the errors property on the cart object) if the Ecom platform reports that item as not available for purchase, so you should almost never have a situation where a customer tries to complete checkout and is only then told that the item is out of stock. If you were having a flash sale or something like that, this situation is still possible, but Violet does our best to surface that error to you at checkout and a customer will never be charged until their order is complete and stock is validated (assuming you are using Violet payment stack).

Why are offers that are out of stock still able to be purchased?

Violet supports physical offers that do not track inventory, for example a print on demand service. This is reflected in the inventory_tracked property of the Violet Sku object. Due to this support, it is possible for Sku to be available for purchase, when configured with the following values:

"in_stock": true,
"qty_available": 0,
"inventory_tracked": false,

Note that because inventory_tracked is false, in_stock is true, indicating “available for purchase” even though qty_available is 0.

You can check the problem offer’s data in the Channel Dashboard’s Offers view by using the Copy Json button present in the Offer Details side pane to see if it matches the above values.

An offer’s inventory_tracked value is mapped from the Merchant’s Ecommerce platform configuration of that offer. So, in the case where a offer has the above values in the Violet Offer record, the Merchant will need to update the configuration for that same offer to tell their Ecommerce platform that inventory_tracked should be true. Typically this is a check box inside the settings of a specific offer/product.

Do orders on a Merchant's platform automatically get deleted via a job if they aren’t completed?

Violet will wait until a SKU is added to the cart before creating a cart (in progress order) on the Merchant's side, only after a SKU is added is a cart will be created on the Merchant's platform. We do not have a job that removes these on our side, because channels use the Violet API in different ways, we have seen carts be completed weeks after creation. We generally recommend that Channels delete their own abandoned carts.

Can we accept merchant specific promo codes?

We do support the use of discounts/promo codes that are created by the merchant in their ecommerce platform.

You can learn more, including a list of supported platforms, in our discount docs.

How does Violet handle returns and refunds?

We don't currently support channel initiated returns. Based on feedback from merchants and platform limitations, the shopper would need to go directly to the merchant to initiate a return.

You can view a diagram of our returns and refund process here

Can we sell CBD products?

This question is a big one in the broader industry. However, as a general FYI, most payment providers do not support the sale of these products. Stripe has a whole section on it, which refers directly to CBD. We do support payment flows that allow the merchant to maintain their setup (as they likely can collect payment on their own website).

Why can't I find my order when I call getOrderById?

A Violet order id, is a cart id that was completed successfully. Only completed carts become orders therefore, only completed carts will return a result when calling the getOrderById endpoint. This is also true when searching for an order Id in the Dashboard.

If you do not see your order Id, try calling getCartById instead. Chances are, the cart was never completed successfully and is therefore still considered a cart not an order.

How do $0 (zero-dollar) orders work?

Violet fully supports $0 orders, which can occur when:

• All SKUs have a price of $0 (promotional items)

• Discounts fully offset the order subtotal

• A combination of free items and discounts brings the total to $0

Key behaviors:

• No payment method required — You can omit payment_method from your request

• Payment is skipped — Violet does not attempt to charge the shopper

• Tax is $0 — No tax liability exists when the taxable base is $0

• No commission — Commission calculation is skipped for $0 orders

The order still progresses through the normal lifecycle and merchants still receive and fulfill $0 orders. See the Zero-Dollar Orders section in the DOS guide for complete details.

Do I need to provide a payment method for $0 orders?

No. When the order total equals $0, you can omit the payment_method from your Create Order request. Violet will:

• Skip payment authorization entirely

• Set capture_status to NOT_REQUIRED on the PaymentTransaction

• Process the order normally through to the merchant

If you do include a payment method on a $0 order, Violet will accept it but will not process any payment.

Is tax charged on $0 orders?

No. When the order subtotal is $0, there is no tax liability:

• $0 price SKUs automatically have tax amount and rate set to $0

• Zero bag subtotals (from discounts or otherwise) result in no tax

This follows standard tax treatment — when the taxable base is $0, no tax is collected.

If you are responsible for tax calculation, ensure your tax provider handles $0 taxable amounts correctly. Most providers will return $0 tax for a $0 base.

What happens to commissions on $0 orders?

Violet does not apply commission on $0 orders:

• Commission calculation is skipped when the order total is $0 or negative

• No distribution records are created for commission amounts

• This prevents negative commission scenarios

Merchants will still receive and fulfill the order, but no commission flows to the channel.

What happens if a $0 order is refunded?

If a merchant initiates a refund on a $0 order:

• Violet creates a refund record with status: EXTERNAL

• No funds are moved since no payment was captured

• The ORDER_REFUNDED webhook is still emitted

• Your system should update order status accordingly but no financial reversal is needed

The refund is recorded for tracking purposes, but since no money changed hands originally, no money is returned.