PRprivy
Coupons

Check a coupon code

Changed on

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

get/coupons/{id}/codes/{code}

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Path parameters

idstring required

The coupon pool's unique identifier (returned as id in coupon responses). Ids are opaque public strings — a numeric id from a Privy dashboard URL is not a valid API id and will 404; list coupons and match by title instead.

codestring required

The coupon code to check, URL-encoded. Matched case-insensitively.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

The code's store-side usage status.

notestring

Fixed caveat that this is a usage counter, not an event log.

Example response

{
  "data": {
    "code": "VIP4X9K2",
    "redeemed": true,
    "usage_count": 1
  }
}

Changes

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

  • fe500ab59b3bRevision changes
    • info

      endpoint added