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.

​

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

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

*The following Shopify discount types are not currently supported:

• Buy X Get Y
• Customer Segments
• Once Per Customer

​

Potential Errors

​

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 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"
}