---
title: "Get a coupon"
method: GET
path: "/coupons/{id}"
tags: ["Coupons"]
---

# Get a coupon

`GET /coupons/{id}`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/coupons/{id}`
- Auth: HTTP bearer

Retrieve a single coupon pool by its identifier — the list rows'
inventory and health, plus `usage_count`, the connected store's
pool-wide redemption counter read live. Privy tracks no redemption
events, so there is no per-code breakdown here; check an individual
code with `GET /v1/coupons/{id}/codes/{code}`.

**Required scope:** `coupons_read`

## Path parameters

- `id` string, required

## Headers

- `Privy-Account-Id` string

## Response `200`

The coupon pool.

- object
  - `data` CouponDetail
    - `id` string: Stable, unique identifier for the coupon pool.
    - `title` string
    - `kind` 'master' | 'unique': `master` is a single shared code; `unique` is a pool of individually generated codes.
    - `platform` 'manual' | 'shopify' | 'bigcommerce' | 'woocommerce': Where the pool's codes live — created by hand in Privy, or synced from the connected store.
    - `master_code` string, nullable: The pool's single shared code. Master pools only — always `null` for unique pools.
    - `prefix_code` string, nullable: The prefix the pool's generated codes start with. Unique pools only — always `null` for master pools, and `null` on unique pools that generate without a prefix.
    - `coupon_codes_remaining` integer, nullable: Unused codes still held in the pool, decreasing as codes are handed out. Manual unique pools only (they hold an uploaded inventory); `null` for store-backed unique pools (Shopify/BigCommerce mint codes on demand and hold no inventory) and for master coupons.
    - `coupon_codes_issued` integer, nullable: Codes Privy has generated for contacts from this pool, increasing over time. Counting began when this field was introduced — earlier issuance is not included, so an older pool can read `0` despite having sent codes. Approximate: a bulk batch whose generation Privy could not confirm is not counted even if the store created its codes. Unique pools only; `null` for master coupons.
    - `healthy` boolean: Whether the pool is syncing and generating codes normally.
    - `failure_message` string, nullable: Human-readable failure detail. `null` when the pool is healthy.
    - `attached_to` object: Every message surface currently pointing at this pool — answers "is this pool actually used anywhere?" without walking the other endpoints. Flow campaign refs cover only each flow's current version (the active one, or the newest draft) — a flow's older versions reference the pool through their own campaign rows and are excluded rather than listed as duplicate same-title refs. Ids round-trip through `GET /v1/displays/{id}` and `GET /v1/campaigns/{id}`.
      - `displays` object[]
        - `id` string
        - `title` string, nullable
      - `campaigns` object[]
        - `id` string
        - `title` string, nullable
        - `type` 'newsletter' | 'flow'
        - `channel` 'email' | 'sms'
    - `usage_count` integer: The connected store's pool-wide redemption counter, read live. Omitted when unavailable — absent is not zero.

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `404`: The requested resource does not exist or does not belong to your account.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `cf0885e90d5a`: 8 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `404`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - …4 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/coupons/:id/get.md)

---

[API](https://skmtc.dev/privy/apis/privy-api.md) - [All operations](https://skmtc.dev/privy/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy/apis/privy-api/revisions/bc29b48dcdd2?raw)