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

# Promotion codes

> Credit partners when a customer uses their coupon, no link or cookie needed.

Links don't work on a podcast, a YouTube video or a flyer. A code does: give Sam `SAM20`, and every payment that uses it is credited to Sam.

 SAM20
checkout
 Billing
payment
 Tolt

In your billing

**payment**ch\_3Qf8…promotion\_code"SAM20"tolt\_referralnullamount4900

In Tolt

**commission**comm\_2nV8…partner"sam"codeSAM20amount1470

A code works alongside links. Use both on any [tracking path](/tracking/overview).

## Create the code

The code has to exist in two places: in Tolt (so Tolt knows it's Sam's) and in your billing system (so the discount applies at checkout).

**Dashboard**

Create the code on the partner in the Tolt dashboard. With Stripe, Paddle or Chargebee connected, choose to sync it and Tolt creates the matching coupon in your billing account too. On Stripe you can also assign an existing promotion code.

**API**

`POST /v2/promotion-codes` records the code in Tolt only. Create the same code in your billing system yourself.

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: code } = await tolt.promotionCodes.create({
  code: "SAM20",
  partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  type: "percentage",
  value: "20",
});
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

res = client.promotion_codes.create(
    code="SAM20",
    partner_id="part_8fKq2LmZx7RtYw3nVbHc5dPj",
    type="percentage",
    value="20",
)
```

```bash cURL theme={"system"}
curl -X POST https://platform.tolt.com/v2/promotion-codes \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAM20",
    "partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj",
    "type": "percentage",
    "value": "20"
  }'
```

`value` is a string: a percent for `percentage` (`"20"` = 20%), or major currency units for `fixed` (`"20"` = \$20.00).

## Attribute the customer

**Billing integration**

Nothing to do. When a Stripe, Paddle or Chargebee payment carries the code, Tolt attributes it to the code's partner. See the [integration guides](/integrations/stripe).

**Tolt API**

When a customer redeems a code in your own checkout, find the partner who owns it, then create the customer with both:

```ts TypeScript theme={"system"}
const entered = "SAM20";
const { data } = await tolt.promotionCodes.list({ search: entered });
// search is a partial match, so compare exactly
const promo = data.find((c) => c.code === entered);

if (promo?.partner_id) {
  await tolt.customers.create({
    email: "jane@example.com",
    partner_id: promo.partner_id,
    promotion_code: entered,
  });
}
```

```bash cURL theme={"system"}
curl "https://platform.tolt.com/v2/promotion-codes?search=SAM20" \
  -H "Authorization: Bearer $TOLT_API_KEY"

curl -X POST https://platform.tolt.com/v2/customers \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj",
    "promotion_code": "SAM20"
  }'
```

Then [record payments](/tracking/payments) for that customer as usual. Payments recorded through the API carry no promotion code, so flows that check one won't match them; condition on the partner or use a dedicated group instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.