Introduction
Getting Started
- Apps
- Pagination
- Authentication
- Environments
- Definitions
Checkout
- Overview
- Getting Started
- Merchants
- Catalog
- Carts and Bags
- Discounts
- Payments
- Payouts
- Webhooks
- Guides
- FAQs
- Resources
- Current Platforms
Violet Connect
- Overview
- Setup
- Payouts
- Commissions
- Guides
- Testing
- FAQs
Relay
Product Info
Checkout FAQs
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 support@violet.io 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
How are shipping costs calculated?
Shipping rates are controlled and configured by the Merchant. Violet does not modify this data in any way. Before shipping rates can be calculated we require a shipping address and any SKUs (line items) that the shopper wishes to purchase. This is the minimum amount of data required by the commerce platforms who are the ones ultimately calculating the rates.
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).
Is there any way to retrieve the estimate for shipping time?
Not at this time.
Few ecommerce platforms provide shipping time estimates in the data returned from their API so we have not yet added this to our integration due to how limited it is. We’re hoping to see this become a supported feature across more platforms in the near future and will then update our integrations to reflect this.
Why can’t I get shipping rates for a product?
This is most likely due to misconfigured shipping zones on the merchant store. Please reach out to the merchant to confirm they have correctly configured shipping for your shipping address’ region. If your merchant is on Shopify, you can refer to our Shopify Shipping Configuration Guide
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 does Violet handle domestic and international shipping?
Using Violet, the steps within checkout are all mirrored on the e-commerce platforms of origin using our Virtual Cart technology. This means you will be able to pull in the exact same shipping options and rates as the Shopper would see on the website of the Merchant the product is coming from. If they support international shipping, those rules apply. If not, it will be empty.
Shopify Questions
How do Shopify Commissions Work?
The commission rate is handled outside of Shopify and is not a part of the pricing within the Shopify order data. Shopify order pricing reflects the total amount paid by the shopper. Since the commission rate is not reflected in the pricing of the Shopify order data the customer will have no visibility into it. See here for more information on commissions.
Why is a merchant seeing draft orders in their Shopify account?
Violet uses the Shopify Draft Orders API to perform the cart/checkout process. When a Violet order is fully submitted, we “complete” the Draft Order in Shopify which causes it to transition to a standard Order. Anything that remains as a Draft Order is essentially an abandoned cart, one that the shopper did not complete. The merchant should not fulfill these as they were not paid for by the shopper.
Currently, Violet does not perform any sort of automated cleanup of incomplete Draft Orders. This is because we prefer to not impose any opinions on how or when they should be cleaned up and try to leave that choice up to our users.
You can use the Delete Cart endpoint to clean up any incomplete carts. This action will result in the deletion of the associated incomplete Draft Order in Shopify.
How are orders deleted in Shopify?
We don’t currently interact with order deletion. Shopify does not provide a webhook for this event as it is not considered to be something that has an effect on the lifecycle of an order. If there was a use case for external order deletion in Shopify it would be something we could consider implementing.
Why are Shopify Merchants returning currently not accepting new orders
for all digital items with a shipping address/method?
The error message [Merchant Name] is currently not accepting new orders. This is likely temporary. Please wait a few moments then try again.
is a generic error message that we return when
an unexpected error occurs trying to submit an order to an e-commerce platform.
However there is a known issue with Shopify where this can happen when you have only DIGITAL
type items in your cart and you add a shipping address and shipping method set.
If you are seeing this error consistently for the same cart and check if the cart meets the above criteria, if it does, the below explanation should help you.
This issue is typically related to a merchant’s third party fulfillment plugin and a bug in Shopify that has been discussed by others in this shopify community page. The end result of this bug is that for this merchant, carts that only have digital items in them cannot have shipping information on that cart in order for that cart to succeed.
To avoid this issue in general we recommend the following:
When all skus in a bag have product_type
= DIGITAL
, you will need to avoid calling /v1/checkout/cart/:cartId/shipping (POST)
and avoid sending a shipping_address
for the customer (note the same_address
field should be false if you are using it so we don’t copy the billing_address
over).
Additionally, since you won’t have a shipping_address
you shouldn’t call /v1/checkout/cart/:cartId/shipping/available
as the call will not work without an address.
Since we price carts automatically when calling setShipping, and you won’t be doing that for this cart, you may need to pass ?price_cart=true
to one of your other calls (and only one to save on rate limits) to make sure the cart is priced before checkout.
Once you have made these changes, you’ll be able to test by creating a cart with a single digital item and you should be able to see it work.
How can we prevent abandoned cart emails?
When a cart is created in Violet, an equivalent cart is often created at the same time in the external commerce platform. If the Violet cart is left in an incomplete state for a period of time, it’s possible that the external commerce platform will consider the equivalent cart abandoned and begin sending abandoned cart emails to the email address on the cart. There is currently no reliable method for Violet to instruct the external commerce platforms to not send these abandoned cart emails.
A workaround solution to prevent your shoppers from seeing any abandoned cart emails is to use an alternative or fake email address while building the cart in Violet. Then when you submit the order for completion, you can provide a new email address which will override any previously applied email address.
We recommend using “Plus Addressing” with any catch-all email address. Some external commerce platforms, including Shopify, create reference accounts in the background for each unique email address. If you use the same catch-all email address without plus addressing the commerce platform may associate orders to this one email address, even after the customer email address on the order is updated to a true customers email address. This will not impact the shopper, but it may impact the merchants reporting system within the commerce platform.
When calling the submit cart endpoint you can use a request body like the following example to override the email address on submission.
{
"order_customer": {
"email": "shopper+unique-value@email.com"
}
}
- Is it possible to send metadata in an order object?
- Can you change the currency of an existing cart?
- What is the referral_id field?
- How are shipping costs calculated?
- Can we override prices of an item or shipping value?
- Can I access the currency exchange rates being used by Violet?
- When a purchase is submitted, what emails does the shopper receive?
- How does Violet handle out of stock issues during checkout?
- Why are offers that are out of stock still able to be purchased?
- Do orders on a Merchant’s platform automatically get deleted via a job if they aren’t completed?
- Can we accept merchant specific promo codes?
- How does Violet handle returns and refunds?
- Can we sell CBD products?
- Is there any way to retrieve the estimate for shipping time?
- Why can’t I get shipping rates for a product?
- Why can’t I find my order when I call getOrderById
- How does Violet handle domestic and international shipping?
- Shopify Questions
- How do Shopify Commissions Work?
- Why is a merchant seeing draft orders in their Shopify account?
- How are orders deleted in Shopify?
- Why are Shopify Merchants returning currently not accepting new orders for all digital items with a shipping address/method?
- How can we prevent abandoned cart emails?