PRprivy
Coupons

List coupons

Changed on

Retrieve a paginated list of your coupon pools with their code inventory and health status.

This is inventory and health only. Privy does not track coupon redemptions — check an individual code's store-side usage counter with GET /v1/coupons/{id}/codes/{code} — and every response carries an in-band note saying so. Two code counters, each null where it doesn't apply: coupon_codes_remaining is a manual unique pool's unused inventory; coupon_codes_issued is how many codes any unique pool has generated for contacts (approximate, and counted only since the field was introduced). Master pools have a single shared code and carry neither.

attached_to lists every display and message campaign currently pointing at each pool, so "is this pool actually wired to my abandoned-cart flow?" needs no dashboard spot-check.

Required scope: coupons_read

get/coupons

Request

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

Query parameters

kind'master' | 'unique'

Only pools of this kind.

platform'manual' | 'shopify' | 'bigcommerce' | 'woocommerce'

Only pools on this platform.

titlestring

Case-insensitive substring match on the pool title.

pageinteger

Page number (starts at 1).

per_pageinteger

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

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

A paginated list of coupon pools.

notestring

Fixed caveat that redemption/usage data is not tracked by Privy.

Example response

{
  "data": [
    {
      "id": "Xk2fW9qLpV",
      "title": "Welcome 10%",
      "master_code": "SAVE20",
      "prefix_code": "VIP",
      "coupon_codes_remaining": 4,
      "coupon_codes_issued": 4210,
      "attached_to": {
        "displays": [
          {
            "id": "gk2P8Zw1Lq",
            "title": "Summer Sale Popup"
          }
        ],
        "campaigns": [
          {
            "id": "Nw8K2rT5xY",
            "title": "June Restock Announcement"
          }
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

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 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