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:

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

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.

​

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

1. Add discounts to cart creation request ([POST]/checkout/cart):

{
  "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):

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

​

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

​

Platform Coverage of Discount Codes

Current support

*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:

{
    "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.
  • Option 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:

  • Option 1:
    • Ignore INVALID discounts and they will be removed from cart during submission.
  • Option 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:
    • Option 1:
      • Ignore INVALID discounts and they will be removed from cart during submission.
    • Option 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.
  • 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.
    • Option 2:
      • Remove ERROR discounts and add the discount code again.
      • If problem persists reach out to Violet.

​

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.

• What does the discounted order look like inside of the e-commerce platform?

  • BigCommerce
    • 
  • Magento
    • 
  • WooCommerce (Accepts multiple discount codes)
    • 

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