Promotion codes

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.

SAM20checkout Billingpayment Tolt

In your billing

paymentch_3Qf8…

promotion_code

tolt_referralnull

amount4900

In Tolt

commissioncomm_2nV8…

partner

codeSAM20

amount1470

A code works alongside links. Use both on any tracking path.

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
API

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.

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

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",
});

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",
)

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

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.

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

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,
  });
}

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

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Create the code

Attribute the customer

​Create the code

​Attribute the customer

Create the code

Attribute the customer