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

# Check a coupon code

`GET /coupons/{id}/codes/{code}`

## Request

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

Check whether an individual code from a Shopify or BigCommerce pool has
been redeemed, read live from the connected store's per-code usage
counter (Privy stores no redemption events).

This is a counter, not an event log: `usage_count` says how many times
the store has accepted the code, but redemption dates, order ids, and
customer attribution are not available — every response repeats this in
an in-band `note`. Manual pools have no store-side counter and return
`422 unsupported_coupon_type`.

A spot check for individual codes — there is no bulk sweep; asking
"which of my thousands of codes were redeemed" is not served by this
endpoint.

Membership semantics: a master pool's single code is matched exactly
(case-insensitively) before the store is asked. Unique-pool codes are
resolved against the store directly — Privy stores no per-code linkage
for platform pools, so a code from one of your OTHER pools would still
resolve; the check never crosses accounts.

**Required scope:** `coupons_read`

## Path parameters

- `id` string, required
- `code` string, required

## Headers

- `Privy-Account-Id` string

## Response `200`

The code's store-side usage status.

- object
  - `data` object
    - `code` string: The code in the store's canonical casing.
    - `redeemed` boolean: Whether the store's usage counter is above zero.
    - `usage_count` integer: How many times the store has accepted the code.
  - `note` string: Fixed caveat that this is a usage counter, not an event log.

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `404`: The pool id is unknown, the code is not the master pool's code, the store no longer knows the code, or the pool's store connection is gone (code `no_connected_store`).
- `422`: Manual pools have no store-side usage counter to check.
- `429`: Rate limit exceeded — either Privy's API rate limit (code `rate_limited`) or the connected store's own quota passed through (code `store_rate_limited`).
- `502`: The connected store's API could not be reached or returned an error. Retry shortly.

## Changes

- **2026-11-05** `cf0885e90d5a`: 12 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 `422`
  - …8 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/coupons/:id/codes/:code/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)