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

# Promotions Overview

> How to create promotions, generate codes, and dispense them to customers

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](/partner/promotions/create-promotion).
* **`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](/partner/promotions/generate-codes).

## End-to-End Workflow

<Steps>
  <Step title="Create the promotion">
    Call [Create Promotion](/partner/promotions/create-promotion). For unique
    one-time codes, pass `code_count`; for a single shared code, pass
    `static_code`. The response returns the promotion `id`.
  </Step>

  <Step title="Wait for code generation">
    `single_use` code generation runs asynchronously. Poll
    [Get Promotion](/partner/promotions/get-promotion) until
    `code_generation_status` is `complete` (or `failed`).
  </Step>

  <Step title="Fetch available codes">
    Call [List Promotion Codes](/partner/promotions/list-codes) with
    `status=unredeemed` to pull codes that have not been redeemed yet — one at
    a time, or up to 10,000 per page.
  </Step>

  <Step title="Dispense codes to customers">
    Assign each fetched code to exactly one recipient before sending it. See
    [Dispensing codes](#dispensing-codes-to-customers) below for the important
    caveat about tracking assignment on your side.
  </Step>

  <Step title="Replenish when running low">
    When your supply of unredeemed codes runs low, call
    [Generate Promotion Codes](/partner/promotions/generate-codes) to add more to
    the same promotion. They become available through List Promotion Codes
    once generation completes.
  </Step>
</Steps>

## 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](/partner/promotions/generate-codes).

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](/partner/promotions/list-codes), and the promotion's
`redemption_count` and `total_codes`
([Get Promotion](/partner/promotions/get-promotion)) reflect overall usage.