> ## Documentation Index
> Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Promo Codes

> Apply manual or automatically discovered promo codes to reduce checkout costs with Rye's Universal Checkout API.

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.

<Tip>
  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.
</Tip>

### Example

Promo codes are provided [when creating a checkout intent](https://docs.rye.com/api-v2-experimental/api-reference/post-checkout-intent#body-promo-codes) 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.

<Tip>
  You can use `discoverPromoCodes` together with manual `promoCodes`. Rye will merge discovered codes with any codes you provide and apply the best one available.
</Tip>

### Example

```json theme={null}
{
    "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.