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

# List Promotions

> Returns active promotions for a merchant

<Info>
  Scope required: `promos.read`
</Info>

This endpoint returns the merchant's active promotions, most recently created
first. Only promotions in the `active` state are returned.

Each promotion flattens the fields of its active code pool onto the promotion
(a promotion has one active pool in practice), including the code
`generation_type`, the running `redemption_count`, and `total_codes`.

### Parameters

<ParamField query="merchant_id" type="string" required>
  Merchant ID
</ParamField>

<Snippet file="pagination/params.mdx" />

### Response

<ResponseField name="id" type="string">
  Promotion ID
</ResponseField>

<ResponseField name="name" type="string">
  Promotion name
</ResponseField>

<ResponseField name="state" type="string">
  Promotion state (always `active` for listed promotions)
</ResponseField>

<ResponseField name="discount_type" type="string">
  Type of discount the promotion applies: `percent`, `item`, or `amount`
</ResponseField>

<ResponseField name="discount_value" type="string">
  Discount amount, as a string. Null if not set.
</ResponseField>

<ResponseField name="minimum_spend" type="string">
  Minimum spend required to redeem, as a string. Null if not set.
</ResponseField>

<ResponseField name="maximum_discount" type="string">
  Maximum discount that can be applied, as a string. Null if not set.
</ResponseField>

<ResponseField name="fine_print" type="string">
  Terms and conditions
</ResponseField>

<ResponseField name="redemption_venue" type="string">
  Where the promotion can be redeemed: `all`, `instore`, or `online`
</ResponseField>

<ResponseField name="starts_at" type="datetime">
  Promotion start timestamp (ISO8601). Null if not set.
</ResponseField>

<ResponseField name="ends_at" type="datetime">
  Promotion end timestamp (ISO8601). Null if not set.
</ResponseField>

<ResponseField name="generation_type" type="string">
  How the pool's codes are generated: `multi_use` (a shared code redeemable
  multiple times) or `single_use` (a batch of one-time codes). Null if the
  promotion has no code pool.
</ResponseField>

<ResponseField name="redemption_count" type="integer">
  Number of times codes in the active pool have been redeemed
</ResponseField>

<ResponseField name="total_codes" type="integer">
  Total number of codes in the active pool
</ResponseField>

<ResponseField name="code_generation_status" type="string">
  Status of asynchronous code generation for the active pool: `none`,
  `in_progress`, `complete`, or `failed`
</ResponseField>

<Snippet file="pagination/response.mdx" />

<RequestExample>
  ```bash List Promotions theme={null}
  curl https://api.thanxsandbox.com/partner/promotions?merchant_id={merchant_id} \
    -X GET \
    -H 'X-ClientId: {client_id}' \
    -H 'Accept-Version: v4.0' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {access_token}'
  ```
</RequestExample>

<ResponseExample>
  ```json Response Example theme={null}
  {
    "promotions": [
      {
        "id": "promo_abc123",
        "name": "Summer 20% Off",
        "state": "active",
        "discount_type": "percent",
        "discount_value": "20.0",
        "minimum_spend": "25.0",
        "maximum_discount": "10.0",
        "fine_print": "Limit one per customer",
        "redemption_venue": "online",
        "starts_at": "2026-06-01T00:00:00Z",
        "ends_at": "2026-08-31T23:59:59Z",
        "generation_type": "single_use",
        "redemption_count": 142,
        "total_codes": 10000,
        "code_generation_status": "complete"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_pages": 1
    }
  }
  ```
</ResponseExample>