List Promotions

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}'

{
  "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
  }
}

GET

partner

promotions

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}'

{
  "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
  }
}

Scope required: promos.read

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

string

required

Merchant ID

integer

The current page of paginated resources.

Default: 1.

integer

Number of records to be returned per API request.

Default: 10
Minimum: 1
Maximum: 100

Response

string

Promotion ID

string

Promotion name

string

Promotion state (always active for listed promotions)

string

Type of discount the promotion applies: percent, item, or amount

string

Discount amount, as a string. Null if not set.

string

Minimum spend required to redeem, as a string. Null if not set.

string

Maximum discount that can be applied, as a string. Null if not set.

string

Terms and conditions

string

Where the promotion can be redeemed: all, instore, or online

datetime

Promotion start timestamp (ISO8601). Null if not set.

datetime

Promotion end timestamp (ISO8601). Null if not set.

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.

integer

Number of times codes in the active pool have been redeemed

integer

Total number of codes in the active pool

string

Status of asynchronous code generation for the active pool: none, in_progress, complete, or failed

hash

Pagination information

Show pagination

integer

Current page

integer

Number of records return per page

integer

The total number of available pages

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}'

{
  "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
  }
}

Create Promotion Get Promotion

⌘I

Merchant & Partner API

Reference

List Promotions

Parameters

Response

​Parameters

​Response

Parameters

Response