# Discounts A discount code is a unique code that corresponds to a discount rate or rule inside of an e-commerce platform. A code is provided by a Shopper at checkout to activate the discount. This is a method often used to provide discounts to select groups and individuals, or to collect data regarding certain actions. These codes can be used as incentives and are often provided by merchants as part of a marketing campaign. {% hint style="info" %} Discounts can also be referred to as promo codes, however, these are *different* from ‘promotions’. Violet defines ‘promotions’ as automatic changes to the price of a cart based on preset rules. These are applied without the presence of a code. For example a "Retail Price" vs a "Sale Price". Violet supports promotions according to this definition when using the basic checkout flow [here](https://docs.violet.io/prism/overview/place-an-order). {% endhint %} ## How Discount Codes Work ### Discount Code Creation Discounts and discount codes are controlled by Merchants on their E-Commerce platforms. For a merchant to create a discount code, they need to take the following steps in their platform: 1. Find the discount code / coupon area * Some platforms put it under marketing 2. Click on new discount code / coupon * Some platforms call them price / cart rules 3. Add all the rules and conditions for the discount code 4. Define the discount code 5. Save 6. Provide the generated code to the user or channel ### Getting the discount If a discount code has been created by a Merchant, during checkout, the discount code is entered into a field usually marked as “discount” or “coupon code” by the shopper. If this code is valid, the platform will automatically apply the discount to the order total which will be reflected in the price of the cart in Violet. The discount can be a percentage off the total purchase price, fixed dollar amount off the total purchase price, free shipping, etc. *** ## When to use a Discount Code **1. Merchants provide a code to their shoppers** In this scenario, the Shopper has the code and they would enter this value into either the Merchants website or your experience. Violet ensures the discount codes that would work on their website will also work on in your app. This means your shoppers will not be incentivised to purchase from the merchant directly if they have a discount code. **2. Merchants provide a code to a partner or Channel for certain discounts** There may be a scenario in which you want to offer an agreed upon discount for certain products or rules in relationship with a merchant. One way to handle this is for the merchant to create a discount code with the appropriate rules, and provide it to you directly. This code would not be distributed to their shoppers as normal, but instead could be integrated into your code or distributed only to your users. *** ## How to use a Discount Code with Violet Discount codes can be added during cart creation (\[POST]`/checkout/cart`) or through an exclusive endpoint (\[POST]`/checkout/cart/:cart_id/discounts`) by providing the `code` and `merchant_id`. For more information, see our [API Reference](https://docs.violet.io/api-reference/orders-and-checkout/cart-discounts/add-discount-to-cart). Every discount code provided is validated against the platform to check for its existence, validity and to get the total discount amount if applicable. *** ## Discount statuses * `PENDING` - Discount added to cart, but not applied to merchant platform yet * `APPLIED` - Discount added to cart, validated and applied to merchant platform * `INVALID` - Invalid discount in merchant platform, check order errors for details * `NOT_SUPPORTED` - Platform currently not supported * `ERROR` - Unexpected error applying discount, check order errors for details * `EXPIRED` - Discount previously applied that is no longer valid in the merchant platform *** ## Supported Platforms | Platforms | Discount Code via API | Applied Immediately | (Re-) Checked During Cart Pricing | | ----------- | --------------------- | ----------------------------------------------- | --------------------------------- | | BigCommerce | ✅ | ✅ | ✅ | | Magento | ✅ | ✅ | ✅ | | WooCommerce | ✅ | Code is in `PENDING` state until cart is priced | ✅ | | ECWID | ✅ | Code is in `PENDING` state until cart is priced | ✅ | | Shopify\* | ✅ | ✅ | ✅ | | Wix | ✅ | ✅ | ✅ | \*The following Shopify discount types are not currently supported: * Buy X Get Y * Customer Segments * Once Per Customer *** ## Potential Errors {% hint style="info" %} Discount errors are not blocking. They are set to the error status along with an error message and will be removed during order submission if not fixed. {% endhint %} ### Invalid discounts Discount codes not recognized by platforms are set as `INVALID`, and an error message is added to the order. Error sample: ``` { "id": 10153, "order_id": 10634, "bag_id": 10645, "type": "EXTERNAL_ADD_DISCOUNT_CODE", "message": "The coupon code isn't valid. Verify the code and try again.", "date_created": "2023-05-24T14:21:24+0000" } ``` #### Solutions: 1. Ignore `INVALID` discounts and they will be removed from cart during submission. 2. Remove `INVALID` discounts and add a different discount code. ### Multiple discounts Most platforms supports only one discount code at a time, so for such platforms the discounts are set as `INVALID` and an error message is added to the order. Currently only WooCommerce supports multiple discount codes. Error sample: ``` { "id": 10152, "order_id": 10633, "bag_id": 10644, "type": "EXTERNAL_ADD_DISCOUNT_CODE", "message": "Multiple discount codes not supported by platform.", "date_created": "2023-05-24T13:43:55+0000" } ``` #### Solutions 1. Ignore `INVALID` discounts and they will be removed from cart during submission. 2. Remove `INVALID` discounts and add a single discount code again. ### Expired discounts Discount codes that were previously applied but are not valid in the platform anymore are set to `EXPIRED` and later removed from the order. **Example** * A valid discount code is added to cart, priced and set to `APPLIED` * This same discount code is disabled in the merchant platform for any reason * Discount code reached usage limit * Merchant changed rules and it doesn’t apply to cart anymore * Merchant manually disabled it * When cart is priced again, or during cart submission, Violet will check the discount codes again in the platform. If they no longer apply to cart, the discount is now considered `EXPIRED` * Finally, since discounts are non-blocking, any `EXPIRED` discount is removed from cart during submission #### Solutions 1. Ignore `INVALID` discounts and they will be removed from cart during submission. 2. Remove `INVALID` discounts and add a different discount code. ### Unexpected error In the case of an unexpected error, the discount is set to `ERROR` and an error message is added to the order. The channel has the option to ignore it and continue the cart through checkout. If it is still present in the `ERROR` state at the time of order submission, it will be removed. #### Solutions 1. Ignore `ERROR` discounts and they will be removed from cart during submission. 2. Remove `ERROR` discounts and add the discount code again. * If problem persists reach out to Violet. *** ### Customer Restricted Discounts Some discount codes may have customer limitations such as "Once Per Customer" or "New Customers Only", etc. The external commerce platforms typically require an email address in order to determine if the discount code can be used by the current customer. For this reason it is recommended that a customer email address is available to provide to the external commerce platform when the discount code is being applied. There are currently two ways to solve for this requirement. **Cart Level Email Address**\ Use the email address on the cart. If you apply a customers email address to a cart before you add the discount code that email address will be provided to the external commerce platform for code validation. This behavior also applies if you are adding the discount code on cart creation, so long as you also include a customers email address on cart creation. **Discount Level Email Address**\ Provide an email address directly with the discount code. When applying a discount code you can include a customer email address in the `email` property of the discount object. When this property is populated it will take priority over any previously applied customer email address on the cart. Any value provided is limited to the discount itself and will not change the email address on the cart. This method is recommended if you use a catch-all email address to [prevent abandoned cart emails](https://docs.violet.io/faqs/checkout#how-can-we-prevent-abandoned-cart-emails.md) until the point of order submission. See the following example for applying a customer email address with the discount code. ``` { "code": "ONCE_PER_CUSTOMER_DISCOUNT_CODE", "merchant_id": 10000, "email": "email@example.com" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.violet.io/prism/checkout-guides/discounts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.