Skip to main content
Promotions let a partner (for example, a marketing platform such as Klaviyo) issue discount codes to a merchant’s customers. This guide explains the code model and the end-to-end workflow, including how to hand out unique one-time codes and replenish them as they run out.

​
Code Models

A promotion holds its codes in a pool. The pool’s generation_type determines how codes behave:
  • multi_use — a single shared code (a “universal” code) that many customers can redeem. Created by supplying static_code at creation.
  • single_use — a batch of unique, one-time codes, each intended for a single customer. Created by supplying code_count at creation, and topped up later with Generate Promotion Codes.

​
End-to-End Workflow

1

Create the promotion

Call Create Promotion. For unique one-time codes, pass code_count; for a single shared code, pass static_code. The response returns the promotion id.
2

Wait for code generation

single_use code generation runs asynchronously. Poll Get Promotion until code_generation_status is complete (or failed).
3

Fetch available codes

Call List Promotion Codes with status=unredeemed to pull codes that have not been redeemed yet — one at a time, or up to 10,000 per page.
4

Dispense codes to customers

Assign each fetched code to exactly one recipient before sending it. See Dispensing codes below for the important caveat about tracking assignment on your side.
5

Replenish when running low

When your supply of unredeemed codes runs low, call Generate Promotion Codes to add more to the same promotion. They become available through List Promotion Codes once generation completes.

​
Dispensing Codes to Customers

A single-use code is intended for one customer, but the API only knows whether a code has been redeemed (used at the point of sale) — not whether you have already handed it out. A code you emailed to a customer this morning is still unredeemed until they actually use it. This means you must track assignment on your side:
  • Fetch a batch of unredeemed codes and record which recipient you assign each one to.
  • Never send the same code to two customers. Because a just-sent code is still unredeemed, the API cannot dedupe this for you.
  • Use your own record of assigned codes — not the API’s unredeemed count — to decide when to replenish.
This is the standard integration pattern for marketing platforms that manage their own send/replenishment logic.

​
Reconciling Redemptions

Once a customer redeems a code, it reports status: redeemed in List Promotion Codes, and the promotion’s redemption_count and total_codes (Get Promotion) reflect overall usage.