---
title: "One coupon, live from TikTok"
method: GET
path: "/promotions/coupons/{coupon_id}"
tags: ["Promotions"]
---

# One coupon, live from TikTok

`GET /promotions/coupons/{coupon_id}`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/promotions/coupons/{coupon_id}`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

## Path parameters

- `coupon_id` string, required

## Response `200`

Successful Response

- PromotionCouponResponse
  - `data` PromotionCouponOut, required: A coupon as TikTok describes it (read-only: coupons are created in Seller Center).
    - `coupon_id` string, required
    - `title` string, required
    - `status` string, nullable
    - `display_type` string, nullable
    - `promo_code` string, nullable
    - `product_scope` string, nullable
    - `product_ids` string[]
    - `create_time` integer, nullable: Milliseconds since the epoch, as TikTok returns it.
    - `update_time` integer, nullable: Milliseconds since the epoch, as TikTok returns it.
    - `claim_duration` object: TikTok's object as sent.
    - `redemption_duration` object
    - `discount` object
    - `threshold` object
    - `usage_limits` object: single_buyer_claim_limit, total_claim_limit, redemption_limit.
    - `usage_stats` object: claimed_count, redeemed_count. Only GET /promotions/coupons/{coupon_id} returns it.
    - `display_channels` string[]: Only the single-coupon read returns it.
    - `target_buyer_segment` string, nullable
    - `creation_source` string, nullable

## Other responses

- `400`: Multi-shop key or invalid id.
- `403`: The shop's TikTok grant lacks `seller.promotion.info` (`SCOPE_NOT_GRANTED`).
- `404`: No such activity or coupon.
- `409`: The shop's TikTok connection needs re-authorizing (`SHOP_NOT_CONNECTED`).
- `422`: Validation Error
- `429`: TikTok is rate limiting this shop (`UPSTREAM_RATE_LIMITED`).
- `502`: TikTok did not complete the request (`UPSTREAM_ERROR`). For a UK shop, with `details.reason` and `Retry-After`, its customer-service token could not be renewed in time.

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-28** `b703ac3d3141`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `502`
- **2026-10-25** `84094c04c9fd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/promotions/coupons/:coupon_id/get.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)