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

# Update Coupon

> Deactivate or reactivate a coupon's redemption gate.

Flips whether a coupon can still be redeemed. `active: false` stops new
subscriptions from applying the code; subscriptions that already carry the
discount keep it — nothing already booked changes. `active: true` restores
redeemability. The coupon's code, discount and duration are immutable after
[creation](/api-reference/coupons/create); read the current state with
[Get Coupon](/api-reference/coupons/get).

## Parameters

| Parameter | Type          | Required | Description      |
| --------- | ------------- | -------- | ---------------- |
| `id`      | string (UUID) | Yes      | Coupon ID (path) |

## Request Body

| Parameter | Type    | Required | Description                                 |
| --------- | ------- | -------- | ------------------------------------------- |
| `active`  | boolean | Yes      | `false` to deactivate, `true` to reactivate |

## Example Request

```bash theme={null}
curl -X PUT https://api.recurso.dev/v1/coupons/6f3c2a91-4b7e-4d0a-9c1e-8a2f5b7d3e10 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'
```

## Response

The response is an action shape, not the coupon object:

```json theme={null}
{
  "status": "deactivated"
}
```

| Field    | Type   | Description                                                             |
| -------- | ------ | ----------------------------------------------------------------------- |
| `status` | string | `deactivated` when `active` was `false`, `activated` when it was `true` |

## Errors

| Status | Code                | When                                                                                     | Fix                                                              |
| ------ | ------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `400`  | `validation_failed` | `id` is not a valid UUID, or the body is malformed / missing the required `active` field | Pass the coupon's UUID and a body with a boolean `active`        |
| `401`  | `unauthorized`      | Missing or invalid API key / session                                                     | Send `Authorization: Bearer $API_KEY`                            |
| `404`  | `not_found`         | No coupon with that ID in your tenant                                                    | Check the ID against [List Coupons](/api-reference/coupons/list) |
| `500`  | `internal_error`    | Persisting the change failed                                                             | Retry; contact support if it persists                            |

Errors use the standard envelope — see [Errors](/api-reference/errors).


## OpenAPI

````yaml PUT /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 <api_key>

    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}:
    put:
      tags:
        - Coupons
      summary: Deactivate or reactivate a coupon
      description: >
        Flips the redemption gate. `active: false` stops new subscriptions from
        redeeming the code; existing subscriptions keep their applied discount.
        `active: true` restores redeemability.
      operationId: updateCoupon
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - active
              properties:
                active:
                  type: boolean
      responses:
        '200':
          description: Coupon updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - activated
                      - deactivated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials (API key or session cookie).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Tenant API key obtained from `POST /auth/register` or `POST
        /v1/developer/keys`.

````