Skip to main content
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

​
merchant_id
string
required
Merchant ID
​
page
integer
The current page of paginated resources.
  • Default: 1.
​
per_page
integer
Number of records to be returned per API request.
  • Default: 10
  • Minimum: 1
  • Maximum: 100

​
Response

​
id
string
Promotion ID
​
name
string
Promotion name
​
state
string
Promotion state (always active for listed promotions)
​
discount_type
string
Type of discount the promotion applies: percent, item, or amount
​
discount_value
string
Discount amount, as a string. Null if not set.
​
minimum_spend
string
Minimum spend required to redeem, as a string. Null if not set.
​
maximum_discount
string
Maximum discount that can be applied, as a string. Null if not set.
​
fine_print
string
Terms and conditions
​
redemption_venue
string
Where the promotion can be redeemed: all, instore, or online
​
starts_at
datetime
Promotion start timestamp (ISO8601). Null if not set.
​
ends_at
datetime
Promotion end timestamp (ISO8601). Null if not set.
​
generation_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.
​
redemption_count
integer
Number of times codes in the active pool have been redeemed
​
total_codes
integer
Total number of codes in the active pool
​
code_generation_status
string
Status of asynchronous code generation for the active pool: none, in_progress, complete, or failed
​
pagination
hash
Pagination information
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
  }
}