Discounts: Using a Code
What is a Discount Code?
A discount code is a unique code that corresponds to a discount rate or rule inside of an e-commerce platform. A code 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. Also called promo codes, this is different from a ‘promotion’.
We define ‘promotions’ as automatic changes to the price of a cart based on preset rules. These are applied without the presence of a code. Violet supports promotions according to this definition if you are using the Checkout API to iterate through the steps of the cart.
How Discount Codes Work
Discount Code Creation
Merchant takes the following steps in their platform:
- Find the discount code / coupon area
- Some platforms put it under marketing
- Click on new discount code / coupon
- Some platforms call them price / cart rules
- Add all the rules and conditions for the discount code
- Define the discount code
- Save
- Provide the generated code to the user or channel
Getting the discount
At checkout, the discount code is entered into a field usually marked a discount or coupon code. When a customer enters a valid discount code, the platform will automatically apply the discount to the order total. 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 the website, also work on in your app. This means your shoppers will never be disappointed if they have a code they wanted to redeem at the time of purchase.
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
At 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
.
Every discount code provided is validated against the platform to check for its existence and to get the total discount amount if applicable.
ℹ️ Go to Checkout and Quick Checkout docs for more details on each step.
Options
There are two options for applying a discount code: a) at initial cart creation and b) to an already existing cart.
A. Apply Discount Code at Cart Creation
During cart creation by providing a list of codes
and merchant_ids
- Add discounts to cart creation request ([POST]
/checkout/cart
):
Merchant ids must match with sku merchant ids otherwise they will be ignored.
{
"base_currency": "USD",
"wallet_based_checkout": false,
"skus": [
{
"sku_id": 99638,
"quantity": 1
}
],
"discounts": [
{
"code": "20p_off",
"merchant_id": 22
}
]
}
B. Apply Discount Code to Existing Cart
Add discount to existing cart by providing a single code
and merchant_id
([POST]/checkout/cart/:cart_id/discounts
):
Merchant ids must match with existing sku merchant ids in cart otherwise it will be ignored.
{
"code": "20p_off",
"merchant_id": 22
}
Both endpoints will return the entire cart with the discounts applied to correct bags. See the “discounts” sections below:
{
"id": 10632,
"token": "b1e4032238424888b6a360b6686cc070",
"user_id": 10002,
"app_id": 10001,
"developer_id": 10001,
"bags": [
{
"id": 10643,
"order_id": 10632,
"merchant_id": 22,
"app_id": 10001,
"status": "IN_PROGRESS",
"fulfillment_status": "PROCESSING",
"financial_status": "UNPAID",
"skus": [
{
"id": 10927,
"merchant_id": 22,
"app_id": 10001,
"product_id": "525a1e59bebd48e7a2d431d666367b5f",
"sku_id": 99638,
"external_id": "MS-Champ-XL",
"name": "Champ Tee Extra Large",
"quantity": 1,
"price": 2500,
"weight": 0.5,
"available": true,
"status": "IN_PROGRESS",
"product_type": "PHYSICAL",
"line_price": 2500
}
],
"taxes": [],
"sub_total": 2500,
"taxes_included": false,
"transactions": [],
"external_checkout": true,
"commission_rate": 0.0,
"date_created": "2023-05-23T20:37:33+0000",
"remorse_period_ends": "2023-06-22T20:37:33+0000",
"currency": "USD",
"external_currency": "USD",
"channel": "APP",
"platform": "MAGENTO",
"fulfillments": [],
"discounts": [
{
"id": 10367,
"bag_id": 10643,
"status": "APPLIED",
"type": "CODE",
"code": "20p_off",
"date_created": "2023-05-23T20:37:33+0000",
"date_last_modified": "2023-05-23T20:37:36+0000"
}
],
"wallet_based_checkout": false,
"bag_id": 10643,
"bag_status": "IN_PROGRESS",
"merchant_name": "Magento Shared's Store"
}
],
"sub_total": 2500,
"status": "IN_PROGRESS",
"is_guest": true,
"date_created": "2023-05-23T20:37:33+0000",
"date_last_modified": "2023-05-23T20:37:33+0000",
"priced": false,
"wallet_based_checkout": false,
"currency": "USD",
"errors": [],
"channel": "APP",
"currency_symbol": "$",
"stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
"guest": true,
"intent_based_checkout": false,
"order_id": 10632,
"order_status": "IN_PROGRESS"
}
Once the cart is priced all available discount information is filled and returned. See “discounts” section below:
{
"id": 10632,
"token": "b1e4032238424888b6a360b6686cc070",
"user_id": 10002,
"app_id": 10001,
"developer_id": 10001,
"customer": {
"user_id": 10002,
"first_name": "Evandro",
"last_name": "Gomes",
"email": "evandro.gomes@violet.io",
"name": "Evandro Gomes"
},
"bags": [
{
"id": 10643,
"order_id": 10632,
"merchant_id": 22,
"app_id": 10001,
"status": "IN_PROGRESS",
"fulfillment_status": "PROCESSING",
"financial_status": "UNPAID",
"skus": [
{
"id": 10927,
"merchant_id": 22,
"app_id": 10001,
"product_id": "525a1e59bebd48e7a2d431d666367b5f",
"sku_id": 99638,
"external_id": "MS-Champ-XL",
"name": "Champ Tee Extra Large",
"quantity": 1,
"price": 2500,
"weight": 0.5,
"available": true,
"status": "IN_PROGRESS",
"product_type": "PHYSICAL",
"line_price": 2500
}
],
"shipping_method": {
"type": "FLAT_RATE_PRICE",
"carrier": "OTHER",
"label": "Flat Rate",
"price": 500,
"id": 10644,
"shipping_method_id": "flatrate_flatrate",
"bag_id": 10643,
"merchant_id": 22
},
"taxes": [],
"sub_total": 2500,
"shipping_total": 500,
"tax_total": 0,
"discount_total": 500,
"total": 2500,
"taxes_included": false,
"transactions": [],
"external_checkout": true,
"commission_rate": 0.0,
"date_created": "2023-05-23T20:37:33+0000",
"remorse_period_ends": "2023-06-22T20:37:33+0000",
"currency": "USD",
"external_currency": "USD",
"channel": "APP",
"platform": "MAGENTO",
"fulfillments": [],
"discounts": [
{
"id": 10367,
"bag_id": 10643,
"status": "APPLIED",
"type": "CODE",
"value_type": "PERCENTAGE",
"code": "20p_off",
"amount_total": 500,
"date_created": "2023-05-23T20:37:33+0000",
"date_last_modified": "2023-05-23T20:38:34+0000"
}
],
"wallet_based_checkout": false,
"bag_id": 10643,
"bag_status": "IN_PROGRESS",
"merchant_name": "Magento Shared's Store"
}
],
"shipping_address": {
"name": "Evandro Gomes",
"city": "Seattle",
"state": "WA",
"country": "US",
"postal_code": "98101",
"type": "SHIPPING",
"first_name": "Evandro",
"last_name": "Gomes",
"address_1": "123 Main St NEWS"
},
"billing_address": {
"name": "Evandro Gomes",
"city": "Seattle",
"state": "WA",
"country": "US",
"postal_code": "98101",
"type": "BILLING",
"first_name": "Evandro",
"last_name": "Gomes",
"address_1": "123 Main St NEWS"
},
"sub_total": 2500,
"shipping_total": 500,
"tax_total": 0,
"discount_total": 500,
"total": 2500,
"status": "IN_PROGRESS",
"is_guest": true,
"date_created": "2023-05-23T20:37:33+0000",
"date_last_modified": "2023-05-23T20:40:32+0000",
"priced": true,
"wallet_based_checkout": false,
"currency": "USD",
"errors": [],
"channel": "APP",
"currency_symbol": "$",
"stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
"guest": true,
"intent_based_checkout": false,
"order_id": 10632,
"order_status": "IN_PROGRESS"
}
Notice that discounts are non-blocking at Violet. It means that when a cart
with discounts is submitted, only APPLIED
discounts are considered, all
other discount statuses and errors are removed from cart.
How to remove a discount
Discounts can be removed from bags through the [DELETE] /checkout/cart/:cart_id/discounts/:discount_id
endpoint. The cart will be returned with current status without the previously applied discount.
Discount statuses
PENDING
- Discount added to cart, but not applied to merchant platform yetAPPLIED
- Discount added to cart, validated and applied to merchant platformINVALID
- Invalid discount in merchant platform, check order errors for detailsNOT_SUPPORTED
- Platform currently not supportedERROR
- Unexpected error applying discount, check order errors for detailsEXPIRED
- Discount previously applied that is no longer valid in the merchant platform
Platform Coverage of Discount Codes
Current support
Platforms | Discount code via API | Applied right away | (Re-) Checked during cart pricing |
---|---|---|---|
BigCommerce | ✅ | ✅ | ✅ |
Magento | ✅ | ✅ | ✅ |
WooCommerce | ✅ | Code is in PENDING state until cart is priced | ✅ |
Shopify* | ✅ | ✅ | ✅ |
*The following Shopify discount types are not currently supported.
Potential Errors
ℹ️ Discount errors are not blocking. In case of errors they are set to proper status along with an error message and removed during order submission if not fixed.
- Invalid discounts
- Discount codes not recognized by platforms are set as
INVALID
, and an error message is added to the order. - Error sample:
- Discount codes not recognized by platforms are set as
{
"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:
- Option 1:
- Ignore
INVALID
discounts and they will be removed from cart during submission.
- Ignore
- Option 2:
- Remove
INVALID
discounts and add a different discount code.
- Remove
- Option 1:
-
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:
- Most platforms supports only one discount code at a time, so for such platforms the discounts are set as
{
"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:
- Option 1:
- Ignore
INVALID
discounts and they will be removed from cart during submission.
- Ignore
- Option 2:
- Remove
INVALID
discounts and add a single discount code again.
- Remove
- Option 1:
-
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
- A valid discount code is added to cart, priced and set to
- Solutions:
- Option 1:
- Ignore
INVALID
discounts and they will be removed from cart during submission.
- Ignore
- Option 2:
- Remove
INVALID
discounts and add a different discount code.
- Remove
- Option 1:
- Discount codes that were previously applied but are not valid in the platform anymore are set to
-
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 theERROR
state at the time of order submission, it will be removed. - The channel can also remove the discount code and retry if would like.
- Solutions:
- Option 1:
- Ignore
ERROR
discounts and they will be removed from cart during submission.
- Ignore
- Option 2:
- Remove
ERROR
discounts and add the discount code again. - If problem persists reach out to Violet.
- Remove
- Option 1:
- In the case of an unexpected error, the discount is set to
FAQs
-
Can I use a discount code on platforms that don’t support?
- It’s possible to add discount codes to unsupported platforms, they will have the
NOT_SUPPORTED
status and will be ignored during order submission. No errors.
- It’s possible to add discount codes to unsupported platforms, they will have the
-
What does the discounted order look like inside of the e-commerce platform?
- BigCommerce
- Magento
- WooCommerce (Accepts multiple discount codes)
- BigCommerce
-
How long does the API call usually take to add a discount?
- Most platforms allow adding discount codes during cart creation, so this approach doesn’t add relevant time to API call
- The add discount API vary per platform, taking around 1 second.
-
What’s the best architectural approach for using the discount code on add cart versus using the dedicated endpoint?
- 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.
-
How is a discount code different from a promo code? Or other promotion?
- 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.
-
How can I test these different scenarios and statuses in Test Mode so I know my app is handling each error and case correctly?
- 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.
- Prepare a cart with
- Steps to get into each of the discount statuses: