> ## Documentation Index > Fetch the complete documentation index at: https://help.privy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a coupon > 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` ## OpenAPI ````yaml openapi/privy-api.yaml GET /coupons/{id} openapi: 3.1.0 info: title: Privy API version: '1.0' description: > The Privy API lets you programmatically manage your contact list and read what you have set up in Privy. Create, update, unsubscribe, and remove contacts; report orders; and read your campaigns, flows, segments, orders, store products, coupon pools, performance reports, and account setup. servers: - url: https://api.privy.com/v1 description: Production security: - bearerAuth: [] tags: - name: Account description: Retrieve information about the authenticated Privy account. - name: Contacts description: Manage your contact list. - name: Imports description: >- Read your contact import history — CSV uploads, connected-provider syncs, and SMS consent imports. - name: Campaigns description: >- Read your message campaigns — email and SMS newsletters, plus the messages your flows send. - name: Displays description: >- Read your on-site displays (popups, flyouts, banners, embedded forms, landing pages). - name: Coupons description: Read your coupon pools, their code inventory, and individual codes. - name: Reports description: >- Read performance reporting — signups, views, conversion rates, and attributed revenue — for your business, displays, and flows. - name: Flows description: Read your automation flows and their configuration. - name: Segments description: Read your customer segments and their membership. - name: Orders description: Report orders placed in your store and read your order history. - name: Products description: Read the product catalog and collections of your connected store. - name: Events description: Ingest custom events to trigger Flows and other automations. paths: /coupons/{id}: get: tags: - Coupons summary: Get a coupon description: | 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` operationId: getCoupon parameters: - $ref: '#/components/parameters/AccountIdParam' - name: id in: path required: true description: >- 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. schema: type: string example: Xk2fW9qLpV responses: '200': description: The coupon pool. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CouponDetail' example: data: id: Xk2fW9qLpV title: Welcome 10% kind: unique platform: shopify master_code: null prefix_code: VIP coupon_codes_remaining: null coupon_codes_issued: 4210 usage_count: 12 healthy: true failure_message: null attached_to: displays: - id: gk2P8Zw1Lq title: Welcome Popup campaigns: [] '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: parameters: AccountIdParam: name: Privy-Account-Id in: header required: false description: > 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. schema: type: string example: S1U2B3A4C5C6T7 schemas: CouponDetail: allOf: - $ref: '#/components/schemas/Coupon' - type: object properties: usage_count: type: integer description: >- The connected store's pool-wide redemption counter, read live. Omitted when unavailable — absent is not zero. example: 12 Coupon: type: object properties: id: type: string description: Stable, unique identifier for the coupon pool. example: Xk2fW9qLpV title: type: string example: Welcome 10% kind: type: string enum: - master - unique description: >- `master` is a single shared code; `unique` is a pool of individually generated codes. platform: type: string enum: - manual - shopify - bigcommerce - woocommerce description: >- Where the pool's codes live — created by hand in Privy, or synced from the connected store. master_code: type: - string - 'null' description: >- The pool's single shared code. Master pools only — always `null` for unique pools. example: SAVE20 prefix_code: type: - string - 'null' description: >- 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. example: VIP coupon_codes_remaining: type: - integer - 'null' description: >- 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. example: 4 coupon_codes_issued: type: - integer - 'null' description: >- 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. example: 4210 healthy: type: boolean description: Whether the pool is syncing and generating codes normally. failure_message: type: - string - 'null' description: Human-readable failure detail. `null` when the pool is healthy. attached_to: type: object description: > 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}`. properties: displays: type: array items: type: object properties: id: type: string example: gk2P8Zw1Lq title: type: - string - 'null' example: Summer Sale Popup campaigns: type: array items: type: object properties: id: type: string example: Nw8K2rT5xY title: type: - string - 'null' example: June Restock Announcement type: type: string enum: - newsletter - flow channel: type: string enum: - email - sms ErrorResponse: type: object properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_client - invalid_scope - unauthorized - insufficient_scope - paid_plan_required - api_access_required - not_found - no_connected_store - conflict - contacts_not_ready - validation_failed - rate_limited - store_unavailable example: validation_failed message: type: string example: One or more fields are invalid details: type: array items: type: object properties: field: type: string example: email message: type: string example: is required responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Bearer token is missing or invalid InsufficientScope: description: Token lacks the required scope for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_scope message: Token does not have the required scope NotFound: description: >- The requested resource does not exist or does not belong to your account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_found message: Not found RateLimited: description: Rate limit exceeded. Retry after the specified time. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 42 X-RateLimit-Limit-Minute: description: Maximum requests allowed per minute. schema: type: integer example: 60 X-RateLimit-Remaining-Minute: description: Requests remaining in the current minute window. schema: type: integer example: 0 X-RateLimit-Reset-Minute: description: Unix timestamp when the minute window resets. schema: type: integer example: 1711929600 X-RateLimit-Limit-Day: description: Maximum requests allowed per day. schema: type: integer example: 10000 X-RateLimit-Remaining-Day: description: Requests remaining in the current day window. schema: type: integer example: 9500 X-RateLimit-Reset-Day: description: Unix timestamp when the day window resets. schema: type: integer example: 1712016000 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limited message: Rate limit exceeded securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API token or OAuth access token description: > Send either an API token or an OAuth access token as `Authorization: Bearer `. See the Authentication page for details. ````