Skip to main content
This page explains how to use promo codes when submitting an order through the API. WIth each order, you can include multiple promo codes to see if there are any applicable discounts. Our system will automatically check each code, and apply the first one that is valid.
  • Currently, the first valid promo code in the list is applied to the order. Coming soon, our system will automatically apply the promo code that provides the highest discount.

​
Example

Promo codes are provided when creating a checkout intent as an array of strings within the promoCodes field, with each string representing a single code. 
{
    "productUrl": "https://www.ulta.com/p/chromaplus-6-pan-eyeshadow-palette-pimprod2052266?sku=2641284",
...
    "quantity": 1,
    "promoCodes": [
        "VALIDCODE1",
        "validcode2",
        "INVALIDCODE3",
        "invalidcode4"
    ],
...
When an offer is retrieved, the first valid promo code will appear in appliedPromoCodes with its discount in discount.amountSubunits. 
 "offer": {
        "appliedPromoCodes": [
            "VALIDCODE1"
        ],
        "cost": {
            "subtotal": {
                "amountSubunits": 1500,
                "currencyCode": "USD"
            },
            "tax": {
                "amountSubunits": 151,
                "currencyCode": "USD"
            },
            "shipping": {
                "amountSubunits": 695,
                "currencyCode": "USD"
            },
            "discount": {
                "amountSubunits": 500,
                "currencyCode": "USD"
            },
            "surcharge": null,
            "total": {
                "amountSubunits": 1846,
                "currencyCode": "USD"
            }
        },
      ...
    }

​
Notes

  • Any invalid codes are ignored, so you don’t need to implement logic to catch errors.
  • Input requirements
    • Alphanumeric, up to 32 characters per promo code.
    • Up to 16 promo codes can be sent with each order.