FAQs

There are two likely scenarios where you can get an invalid credentials error.

1. You are not the Owner of your app:

   While the User Management feature of the Dashboard allows multiple users to login and view the dashboard, only an App’s “Owner” username and password will allow you to generate a token. You can view who your App’s owner is on the team view

2. You are using the wrong App Secret for the environment you are trying to login:

   While your username and password will be the same across environments (test and live) as will your X-Violet-App-Id, this is not true for your X-Violet-App-Secret.

   The X-Violet-App-Secret you retrieve from the Channel dashboard is different depending on the live/test mode toggle. You must use the correct app secret that corresponds to the environment you are trying to login to: test for sandbox-api.violet.io and live for api.violet.io.

We do not currently support metadata on an order. Follow our Changelog or reach out on support@violet.io for more information.

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 know 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.

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.

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

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.

Violet does not currently support overriding prices, however some platforms do support it and we have adding support for those platforms on our future roadmap. Follow our Changelog for updates on this feature.

The real-time exchange rates being utilized by Violet can be accessed through the currencies API. Information around this can be found here, https://docs.violet.io/currencies.

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.

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, be 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).

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.

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.

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, about these in the following docs:

1. https://docs.violet.io/discounts-using-a-code
2. https://docs.violet.io/add-discount-to-cart

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.

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

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.

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).

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.

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

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.

Quick Checkout is currently supported by Shopify, WooCommerce, BigCommerce, Magento, Salesforce Commerce Cloud, Ecwid, and Prestashop.

Yes, one of the main ways quick checkout is optimized is that you send all customer information along with SKU information in the initial create cart request. Simply create the cart with Violet after having gathered all the required information and you will be set.

If your merchant’s offers aren’t showing up in your shopping experience there are a few possibilities.

First you can double check if any of the Merchant’s offers are in Violet’s system using the offers view in the Channel Dashboard and filtering by the Merchant. If you see the offers there, you can rest assured that they are correctly synced in Violet’s system.

If you do not see any offers in the previously mentioned view, there are a few reasons that might explain this:

1. Recently connected Merchants can take some time to initially sync their catalog into Violet. You can view a Merchant’s sync status here.
2. Violet monitors the state of Merchants proactively and based on certain triggers will deactivate them if they are no longer a position to accept orders. You can find out more here.

Violet monitors the state of Merchants proactively and based on certain triggers will deactivate them if they are no longer a position to accept orders. You can find out more here.

Violet keeps it’s offer data in sync with Merchants’ e-commerce platform using a variety of mechanisms, some of which can occasionally take a handful of minutes to fully process.

If you notice an Offer’s image, description, price or any other piece of data is not in sync with what a merchant has set in their e-commerce platform, it is possible that Violet is still working on updating that information. Please check again after a few minutes.

In the case where the changes on the merchant side were not made recently, you can also use the “Resync Offer” button in the channel dashboard:

1. Go to the offers view in the dashboard.
2. Find the appropriate offer.
   Make sure you are looking at the correct offer. All offers contain an external ID that you can use to confirm a match with the product the Merchant has changed.

3. Click on the Offer to view the offer details.
   This view is a direct representation of what is stored in Violet’s system, when this view is showing the correct data, you can rest assured that Violet has the offer data stored correctly in our systems.

4. Double check that the information in this view is not in sync with the data in the Merchant’s e-commerce platform.
5. If it is not correct, scroll to the bottom and use the “Resync Offer” button to refresh the data in Violet’s systems.
6. Confirm that the data is now showing correctly.

If you have completed the above steps, including ensuring that you have the correct external product ID in relation the Merchant’s product, and the data displayed is still not correct, please contact support and provide the offerId as well as the externalId that the merchant changed.

As of now, Violet only supports payments through Stripe. You are however, able to bypass payments with Violet and work with whichever payment provider works best for you if you use our External Payments flow.

Refunds are triggered by a Merchant. If a merchant marks an item as refunded, the refunded amount is returned to the Shoppers card and any transfers made to parties involved are reversed by Violet.

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

Refunds are initiated by the merchant from within their E-commerce platform dashboard. Violet has webhooks that pick up on refund events which we use to update our records before forwarding the updates to the channel who created the order.

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

Cancellations are initiated by the merchant from within their E-commerce platform dashboard. Violet has webhooks that pick up on cancellation events which we use to update our records before forwarding the updates to the channel who created the order.

Violet doesn’t rely on merchant PSP’s. During the onboarding process, we create an “internal” Stripe Express Connect account for this merchant (this only lives within Violet and is different to a traditional Stripe account). Merchants then connect their bank account directly to this Stripe account, which is what is paid out.

See our Payouts section for more info.

Unfortunately, Stripe does not allow cross-border transfers to be made in USD due to differences in KYC regulations for each country. Cross-border transfers require the “Recipient Service Agreement” for linked accounts, and as seen here, the only supported combination as of now for “country name” accounts is “country code” / “currency code”. Our recommendation is to ask the Merchant to connect their local currency bank account instead. We actively monitor the list of settlement currencies though, so if this ever changes, we will let you know.

We just pass the billing address through to the commerce platforms where it’s generally a requirement on their end. Most commerce platforms will not accept orders without a billing address, which historically has been used to determine who is ultimately responsible for paying for the order.

The billing address can sometimes be used for calculating taxes but it’s not a common practice. Most merchants, at least in North America, only use the shipping address for calculating taxes. The choice for which address to use is something the merchant’s can configure in their commerce platform. Violet does not play any role in deciding which address to use. We provide both addresses to the commerce platform, and they eventually provide tax data in return usually without telling us which address they used.

Unfortunately this is a Platform restriction. Some of the platforms we support require both. At this point Violet has the same requirements. The best workaround for now is to send the same address for both we have a property for just that.

You can certainly issue store credit to a Shopper. The key is in how to implement store credit. You have two choices based on whether you use Violet’s integrated payment tools, or your own.

1. Violet Payments
   1. Shopper has $20 of credit from Channel.

      1. Scenario 1: Shopper can buy anything less than the price of the credit (less than $20) at no charge.

         1. Channel uses a company credit card to pay for the purchase. Default behavior of checkout satisfies this requirement. Channel builds the logic to use the company card when tokenizing the payment instead of the Shopper’s credit card.

      2. Scenario 2: Price of the product is $100. Shopper applies the discount to the purchase.

         → Biggest issue here is multiple credit card transaction fees. If you’re ok with that, it’s relatively easy.

         1. When shopper opts to use the credit, the payment method logic changes.
         2. Channel uses a company credit card to pay $100 for the product(s) directly with the Merchant through Violet’s API.
            1. 1st credit card processing fee
         3. Channel charges the Shopper $80.
            1. 2nd credit card processing fee
2. Custom Payments
   1. Same as above. The difference is, it’s your payment stack, so you can determine if you want to have some sort of other payment rules with the Merchant.

      1. Scenario 1: Shopper pay Channel directly for $80 (product total was $100)

         1. Channel pays merchant at the end of the month via ACH for all orders.

            1. Shopper is charged $80 for the $100 item.
            2. Merchant receives the order and it is marked as Paid.
            3. Merchant has not received payment.
            4. Last day of the month the Merchant receives an ACH for all orders from the month.

            → Violet is likely going to introduce this an alternative payout model for the future to make payouts more flexible. However, many parts of the system become more open to abuse, so we’re taking our time in how we approach this.

            Note: this involves the Channel keeping funds for orders placed for a longer period of time than the usual payment processing period. Channel will need to consult tax and legal professionals to ensure they are in compliance with applicable laws.

      2. Scenario 2: 2 credit card processing fees (like scenario 2 above)

In Stripe test mode, you can go through the KYC flow by just clicking on “Use Test Document” / “Use Test Account” etc. as shown in the screenshot he sent. No data will transfer over when moving from test to live. KYC will have to be completed from scratch

When you’re in “test” mode, the Stripe account you create is also a test account. This is so that you can test the full end-to-end checkout flow before any transactions are places in production. Orders placed in sandbox using test credit cards will have money flow through to the fake Stripe account. Stripe requires that you still put in real addresses though, but does not do verification, so addresses of famous landmarks are easy test addresses.

Once you have “live mode” enabled, the Stripe account you connect will be your real stripe account. Your commission from orders placed in production will flow into this account once it has been set up and orders are placed.

Both accounts live simultaneously — to switch between the two, all you need to do is flip between live and test mode from the toggle in the channel dashboard. See Environments for more details.

Merchants have tools to change their commission rate. Channels do not have the ability to change commission rates from their end, and Violet typically does not change it from our end unless there’s an emergency. You can ask the merchant to update the commission rate by doing the following:

1. Navigate to merchant.violet.io/overview,
2. In the section that says “[Your Channel Name]”, hovering over the commission rate current set
3. Clicking “Edit”
4. Confirm that this is a change they are trying to make by following the prompt
5. Enter the new commission rate
6. Submit

Authorization (Hold) vs Capture

Stripe supports both authorizing funds on a card, often referred to as a hold, and actually capturing those funds, or charging the card. Many businesses use these distinctions in their workflows since they often need to happen at different moments in time. Think of a hotel authorizing a card for incidentals and charging (capturing) the funds at checkout.

How Violet uses Authorization and Capture (Stripe V2)

Violet uses these two concepts for a similar purpose as a hotel or rental agency, just on a much smaller timescale. Violet authorizes the payment of a cart first, then completes the order write back to the merchant or merchants’ ecommerce platform and only after all bags have been successfully written does Violet capture funds. This means that we can validate funds exist and check for fraud before creating orders in the merchant’s system, while at the same time, not actually charging a customer in the event there is an error during write back. In the event that an error does occur, the hold will expire and drop off the customer’s bank statement with 7 days, per standard Stripe processes. All three of these actions take place, one after another when an order is submitted to Violet, i.e. during the final call in checkout. Thus the time frame between authorization and capture can potentially be just milliseconds.

Stripe V3 and Wallet (ApplePay)

In Stripe V3 and ApplePay as well as wallets, one of the key differences is that the browser makes a call directly to Stripe with the entered credit card information to authorize funds. This means that when this payment flow is used, on cart submit, Violet skips the authorize call and instead validates that authorization succeeded before continuing on like normal to write back the order and capture funds. Note that this should have no overall impact on the shopper since in this flow they are still not actually charged until write back is complete, and if there is any error during submit or at any point after authorize, the hold will still expire and drop off their bank statement, same as above.

This depends on the payment/payouts method you select. If using Violet, the funds will be process via Stripe and pay the Merchant directly to their Stripe Connect account. If using external payments, you will need to handle the payouts to merchants yourself.

Merchants that have properly set up payout accounts and gone through Stripe KYC automatically get paid out on a 2-day rolling basis. Violet transfers these funds to their Stripe account at point of sale and then Stripe processes a bulk transfer to their connected payout account.

The money goes back to the Shopper, and the money is retrieved from each party. Whoever got their cut, loses their cut. If using Violet’s payment tools, whatever Violet gets charged, we pass on to the channel and invoice at the end of the month. Any penalties incurred for the chargeback will be paid for by the Channel. If a channel is using their own payment tools, they’d pay for the charges they incur.

We calculate the commission based on the Subtotal.

• When a order is submitted, Violet takes into account Stripe fees, tax, shipping and the commission rate associated with any merchants involved before transferring any funds. Violet then charges the customer the full amount, calculates what needs to be sent to each party and uses Stripe to transfer the final amount. This is all automated. Both you and the merchant can visit your own Stripe Express dashboards where you can see the total amounts being transferred to you after each transaction.
• Note that Stripe fees are deducted from the Channel’s commission, not the Merchant’s payout. This will be transparent to the Merchant.
• For example: A Merchant sees a $100 order in the order view on the merchant dashboard, the subtotal is $90 ($10 in shipping and taxes), they have a 10% commission configured in their dashboard with the channel, then they would see a $91 payout in Stripe. 100 - (90 * 0.1) = 91

You can enable payment bypassing by reaching out to us on support@violet.io. When payment bypassing is enabled for an application, the application becomes exempt from all order payment requirements and no longer applies a payment method to a cart. The channel assumes all responsibility for facilitating payments between the shopper and the merchant.

Considerations:

• This feature is immediately available from Violet. Once a channel opts in and is approved the change will generally go into effect within one business day.
• The channel must subscribe to the ORDER_CANCELED, ORDER_REFUNDED, and ORDER_RETURNED webhooks, or the catchall ORDER_UPDATED webhook. This is to ensure that channels can facilitate a refund back to the shopper when necessary. Channel Level of Effort
• The channel is fully responsible for their own payment stack.

This is intended Channels who have a complete payment solution and are able to fully manage transactions between shoppers and merchants.

See External Payments for more information

Currently, all payments for orders placed through Violet are processed outside of the commerce platforms. We use Stripe today for this functionality. During onboarding a merchant will connect their payout account. When an order is placed, their portion will be transferred into their account.

This approach allows us to support a wider range of commerce platforms, as many do not allow for payments to be sent through their API.

Shopify does have this requirement for developers who utilize the Sales Channel SDK. If you are going to use the Sales Channel SDK, you will need to handle payment processing and payouts.

We also support the use of the Draft Orders API, which provides similar functionality to the Sales Channel SDK, but without the on-site payments requirement. This is the most common scenario we see.

Using the Draft Orders API allows you the flexibility to choose whether you’d like to use Violet Payouts or not.

Violet does not currently support linking existing Stripe accounts to our payments flow. Violet uses Stripe Connect to power payouts, which is a core part of Stripe’s product offering and used by companies such as Doordash, Lyft, and Shopify to power their payment stacks. You can read more about it here: https://stripe.com/connect.

Violet specifically uses Stripe Express to ensure that Stripe handles the onboarding and provides you with the ability to control your own payout schedules and connected bank accounts. This information never leaves Stripe and this account is only used by Violet for payouts. The Stripe Express account is not a “full” business Stripe account and goes through simpler KYC. We are constantly improving our payment capabilities though, so you can keep track of our Changelog

We take the current state of the cart (total price including shipping, etc) and updates the cart’s intent with the correct value in stripe. This is done for you automatically when call this method.

The good news is that this should be done automatically when you apply a shipping method to the cart, so ideally you don’t have to do call this endpoint in most cases.

You can learn more about this endpoint in our API Reference.

It’s possible to add discount codes to unsupported platforms, they will have the NOT_SUPPORTED status and will be ignored during order submission. This will not cause any errors blocking checkout.

BigCommerce

Magento

WooCommerce (Accepts multiple discount codes)

The commission would be based on the discounted item price. After a cart has been fully populated and any discounts are applied we request the final pricing for the cart from the external commerce platform and calculate the commission from those values.

Most platforms allow adding discount codes during cart creation, so this approach doesn’t add relevant time to API call.

• The add discount API varies per platform, taking around 1 second.

For a channel just posting orders for the user, it may be better to add all discounts during cart creation saving the extra call.

• For checkout style channels allowing users to add/remove discounts to cart may make sense.

Discount codes and promo codes are used interchangeably in platforms, the same as coupons.

• Some platforms may also offer promotions that are added to carts automatically based on preset rules. This is typically just a “retail price” and a “sale price” with the traditional strike out of the retail price.

• Steps to get into each of the discount statuses:
  • PENDING
    • Add a discount code to a platform that doesn’t process it right away, like WooCommerce.
  • APPLIED
    • Add a valid discount code to a platform that process it right away, like BigCommerce or Magento.
    • Or price a cart with a valid PENDING discount code.
  • INVALID
    • Add any invalid discount code to a platform that process it right away, like BigCommerce or Magento.
    • Or price a cart with a invalid PENDING discount code.
  • NOT_SUPPORTED
    • Add a discount code to any platform that is not listed in our platform coverage table.
  • ERROR
    • Not reproducible in normal circumstances.
  • EXPIRED
    • Prepare a cart with APPLIED discounts, go to merchant platform and disable the discount code, price the cart again.

• While most discount codes can be used with Apple Pay, there is limited support for Free Shipping discount codes.
  • This is because many free shipping codes require a shipping method to have been selected before being applied, but the shopper only selects shipping in the Apple Pay screen, which is after the discount entry screen.
  • You could consider storing the shipping code locally until the shipping method is selected and then applying it, while informing the user that it will be applied at checkout.