Skip to main content
This page explains how to use promo codes when submitting an order through the API. Rye supports two approaches: passing your own codes manually, and automatic promo code discovery.

​
Manual Promo Codes

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, we shuffle the provided promo codes and apply the first one that works. Coming soon, our system will automatically apply the promo code that gives 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"
            }
        },
      ...
    }

​
Automatic Promo Code Discovery

Set discoverPromoCodes: true when creating a checkout intent and Rye will automatically find and apply the best available promo code for the merchant. This is a cost optimization feature — Rye aggregates promo codes from multiple sources, caches them, and selects the code that gives the highest discount during offer retrieval, with no manual sourcing required on your end.

​
How it works

  1. Include "discoverPromoCodes": true in your create checkout intent request.
  2. During offer retrieval, Rye searches its aggregated promo code database for the merchant.
  3. The best available code is applied automatically.
  4. The applied code and discount amount appear in the offer response in the same appliedPromoCodes and discount.amountSubunits fields as manual codes.
You can use discoverPromoCodes together with manual promoCodes. Rye will merge discovered codes with any codes you provide and apply the best one available.

​
Example

{
    "productUrl": "https://www.ulta.com/p/chromaplus-6-pan-eyeshadow-palette-pimprod2052266?sku=2641284",
    "buyer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "212-333-2121",
        "address1": "123 Main St",
        "city": "New York",
        "province": "NY",
        "postalCode": "10001",
        "country": "US"
    },
    "quantity": 1,
    "discoverPromoCodes": true
}

​
Notes

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