> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get Coupon > Fetch a single coupon by ID, including its redemption gate. Returns one coupon as an addressable object — the record behind the dashboard's coupon page. Coupons are tenant-scoped: an ID that belongs to another tenant returns `404`, the same as a missing one. To browse the catalog use [List Coupons](/api-reference/coupons/list); to flip the redemption gate use [Update Coupon](/api-reference/coupons/update). ## Parameters | Parameter | Type | Required | Description | | --------- | ------------- | -------- | ---------------- | | `id` | string (UUID) | Yes | Coupon ID (path) | ## Example Request ```bash theme={null} curl https://api.recurso.dev/v1/coupons/6f3c2a91-4b7e-4d0a-9c1e-8a2f5b7d3e10 \ -H "Authorization: Bearer $API_KEY" ``` ## Response ```json theme={null} { "data": { "id": "6f3c2a91-4b7e-4d0a-9c1e-8a2f5b7d3e10", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "code": "SUMMER25", "discount_type": "percent", "discount_value": 25, "duration": "repeating", "duration_months": 3, "active": true, "created_at": "2026-04-01T09:00:00Z", "updated_at": "2026-04-01T09:00:00Z" } } ``` ## Fields | Field | Type | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string (UUID) | Coupon ID | | `tenant_id` | string (UUID) | Owning tenant | | `code` | string | The redeemable code, unique per tenant | | `discount_type` | string | `percent` or `amount` | | `discount_value` | integer | Percent (for `percent`) or the discount in minor currency units (for `amount`) | | `duration` | string | `once`, `repeating`, or `forever` | | `duration_months` | integer | Months the discount applies; only present for `repeating` | | `active` | boolean | Whether new subscriptions may redeem the code. Deactivated coupons are rejected at subscription creation; existing subscriptions keep their applied discount | | `created_at` | string (RFC 3339) | Creation timestamp | | `updated_at` | string (RFC 3339) | Last modification timestamp | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `400` | `validation_failed` | `id` is not a valid UUID | Pass the coupon's UUID | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `404` | `not_found` | No coupon with that ID in your tenant (cross-tenant IDs are never leaked) | Check the ID against [List Coupons](/api-reference/coupons/list) | | `500` | `internal_error` | Loading the coupon failed | Retry; contact support if it persists | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/coupons/{id} openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/coupons/{id}: get: tags: - Coupons summary: Get one coupon (tenant-scoped) description: > Fetches a single coupon by id — the addressable object behind the dashboard's coupon page. A missing or cross-tenant id returns 404. operationId: getCoupon parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: The coupon. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Coupon' '404': $ref: '#/components/responses/NotFound' components: schemas: Coupon: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid code: type: string discount_type: type: string enum: - percent - amount discount_value: type: integer format: int64 duration: type: string enum: - forever - once - repeating duration_months: type: - integer - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````