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

# Get Promotion

> Returns a single active promotion

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

This endpoint returns a single active promotion for the merchant. The
promotion must belong to the specified merchant and be in the `active` state,
otherwise a `404 Not Found` is returned.

The fields of the promotion's active code pool are flattened onto the
promotion, including `generation_type`, `redemption_count`, and `total_codes`.

### Parameters

<ParamField path="id" type="string" required>
  Promotion ID
</ParamField>

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

### 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`)
</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`. Poll this field after requesting
  code generation via [Create Promotion](/partner/promotions/create-promotion)
  or [Generate Promotion Codes](/partner/promotions/generate-codes).
</ResponseField>

<RequestExample>
  ```bash Get Promotion theme={null}
  curl https://api.thanxsandbox.com/partner/promotions/promo_abc123?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}
  {
    "promotion": {
      "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"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Promotion not found"
    }
  }
  ```
</ResponseExample>