openapi.yaml

openapi: 3.1.0

info:
  title: Chargebee Billing API
  version: "2024-01"
  description: |
    The Chargebee Billing API lets you manage the full subscription lifecycle — 
    create and update subscriptions, collect payments, issue invoices, and 
    handle revenue recognition.

    ## Authentication

    All requests use HTTP Basic Auth. Pass your API key as the username with 
    an empty password:

    ```bash
    curl https://your-site.chargebee.com/api/v2/subscriptions \
      -u your_api_key:
    ```

    Your API key is scoped to a Chargebee site. Use test-site keys for 
    development and live-site keys for production.

    ## Base URL

    ```
    https://{site}.chargebee.com/api/v2
    ```

    Replace `{site}` with your Chargebee site name.

    ## Versioning

    The API version is set per request using the `chargebee-version` header. 
    If omitted, the default version for your site is used. We recommend 
    pinning to a specific version in production.

    ```
    chargebee-version: 2024-01-01
    ```

    ## Pagination

    List endpoints return a maximum of 100 results. Use `next_offset` from 
    the response to retrieve the next page:

    ```bash
    curl "https://your-site.chargebee.com/api/v2/subscriptions?limit=25&offset={next_offset}"
    ```

    ## Errors

    Chargebee uses standard HTTP status codes. All errors return a JSON 
    body with `api_error_code`, `message`, and `error_code` fields. 
    See [Error Codes](#section/Error-Codes) for a full taxonomy.

  contact:
    name: Chargebee Developer Support
    url: https://www.chargebee.com/docs/
    email: support@chargebee.com
  license:
    name: Proprietary

servers:
  - url: https://{site}.chargebee.com/api/v2
    description: Production
    variables:
      site:
        default: your-site
        description: Your Chargebee site name

tags:
  - name: Subscriptions
    description: |
      Manage the full subscription lifecycle — create, update, cancel, 
      pause, and reactivate subscriptions. A subscription ties a customer 
      to a plan and drives all downstream billing events.
  - name: Invoices
    description: |
      Invoices represent finalized billing events. They are created 
      automatically at the end of each billing cycle or manually via 
      the API. Once created, invoices can be voided but not deleted.
  - name: Customers
    description: |
      Customer records store billing identity and payment methods. 
      A customer can have multiple subscriptions.
  - name: Plans
    description: |
      Plans define pricing, billing frequency, and trial settings. 
      Customers subscribe to plans.

paths:

  # ── SUBSCRIPTIONS ──────────────────────────────────────────────

  /subscriptions:
    get:
      operationId: list-subscriptions
      summary: List subscriptions
      description: |
        Returns a paginated list of subscriptions. Filter by `customer_id`, 
        `status`, or `plan_id` to narrow results.

        Results are sorted by creation date, descending.
      tags: [Subscriptions]
      parameters:
        - name: limit
          in: query
          description: Number of results to return. Maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: |
            Pagination cursor. Pass the `next_offset` value from a 
            previous response to retrieve the next page.
          schema:
            type: string
        - name: customer_id[is]
          in: query
          description: Filter by customer ID (exact match).
          schema:
            type: string
            example: cus_KmQ9xT4pRw2v
        - name: status[is]
          in: query
          description: Filter by subscription status.
          schema:
            $ref: '#/components/schemas/SubscriptionStatus'
        - name: plan_id[is]
          in: query
          description: Filter by plan ID.
          schema:
            type: string
      responses:
        "200":
          description: A paginated list of subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        subscription:
                          $ref: '#/components/schemas/Subscription'
                  next_offset:
                    type: string
                    nullable: true
                    description: |
                      Cursor for the next page. `null` if this is the last page.
              example:
                list:
                  - subscription:
                      id: sub_HxKtL3QmVr9p
                      customer_id: cus_KmQ9xT4pRw2v
                      plan_id: plan_pro_monthly
                      status: active
                      current_term_start: 1704067200
                      current_term_end: 1706745600
                      created_at: 1704067200
                      currency_code: USD
                next_offset: null
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: create-subscription
      summary: Create a subscription
      description: |
        Creates a new subscription for an existing customer. If the plan has 
        a trial period, the subscription starts in `in_trial` status. 
        Otherwise it moves to `active` immediately.

        ### What happens at creation

        1. The subscription is created in `in_trial` or `active` status.
        2. If the plan has an immediate charge (setup fee or first billing 
           cycle), an invoice is generated.
        3. If payment collection is configured, Chargebee attempts to collect 
           the invoice immediately.

        ### Idempotency

        Pass an `Idempotency-Key` header to safely retry failed requests 
        without creating duplicate subscriptions.
      tags: [Subscriptions]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [plan_id, customer_id]
              properties:
                plan_id:
                  type: string
                  description: ID of the plan to subscribe to.
                  example: plan_pro_monthly
                customer_id:
                  type: string
                  description: ID of the customer to subscribe.
                  example: cus_KmQ9xT4pRw2v
                plan_quantity:
                  type: integer
                  description: |
                    Quantity of plan units. Required for per-seat plans. 
                    Defaults to 1.
                  minimum: 1
                  default: 1
                trial_end:
                  type: integer
                  description: |
                    Unix timestamp for a custom trial end date. Overrides 
                    the plan's default trial period. Must be in the future.
                auto_collection:
                  type: string
                  enum: [on, off]
                  description: |
                    Whether to automatically collect payment at renewal. 
                    Defaults to the customer's `auto_collection` setting.
      responses:
        "200":
          description: Subscription created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
                  customer:
                    $ref: '#/components/schemas/Customer'
                  invoice:
                    $ref: '#/components/schemas/Invoice'
                    nullable: true
                    description: |
                      The invoice generated at creation, if any. `null` if 
                      no immediate charge was applicable.
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'

  /subscriptions/{subscription_id}:
    get:
      operationId: retrieve-subscription
      summary: Retrieve a subscription
      description: Returns a single subscription by ID.
      tags: [Subscriptions]
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        "200":
          description: Subscription retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'

  /subscriptions/{subscription_id}/cancel:
    post:
      operationId: cancel-subscription
      summary: Cancel a subscription
      description: |
        Cancels an active or in-trial subscription.

        ### Cancellation timing

        By default, the subscription cancels at the end of the current 
        billing term (`end_of_term: true`). The subscription moves to 
        `non_renewing` status and access continues until term end.

        To cancel immediately, pass `end_of_term: false`. The subscription 
        moves to `cancelled` status immediately and any unused days are 
        credited based on your proration settings.

        ### Dunning

        If a subscription is in `active` status but has an unpaid invoice, 
        cancelling immediately attempts final payment collection before 
        cancelling.
      tags: [Subscriptions]
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                end_of_term:
                  type: boolean
                  default: true
                  description: |
                    `true` — cancel at the end of the current billing term.  
                    `false` — cancel immediately.
                cancel_reason_code:
                  type: string
                  description: |
                    Reason for cancellation. Used in churn analytics. 
                    Must match a code configured in your Chargebee site.
      responses:
        "200":
          description: Subscription cancelled successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'

  # ── INVOICES ───────────────────────────────────────────────────

  /invoices:
    get:
      operationId: list-invoices
      summary: List invoices
      description: |
        Returns a paginated list of invoices. Voided invoices are included 
        by default. To exclude them from revenue reporting, filter by 
        `status[is_not]=voided`.
      tags: [Invoices]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: customer_id[is]
          in: query
          schema:
            type: string
        - name: status[is]
          in: query
          schema:
            $ref: '#/components/schemas/InvoiceStatus'
        - name: status[is_not]
          in: query
          description: Exclude invoices with this status.
          schema:
            $ref: '#/components/schemas/InvoiceStatus'
        - name: date[after]
          in: query
          description: Filter invoices created after this Unix timestamp.
          schema:
            type: integer
      responses:
        "200":
          description: A paginated list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        invoice:
                          $ref: '#/components/schemas/Invoice'
                  next_offset:
                    type: string
                    nullable: true
        "401":
          $ref: '#/components/responses/Unauthorized'

  /invoices/{invoice_id}:
    get:
      operationId: retrieve-invoice
      summary: Retrieve an invoice
      description: Returns a single invoice by ID.
      tags: [Invoices]
      parameters:
        - name: invoice_id
          in: path
          required: true
          schema:
            type: string
          example: inv_KmQ9xT4pRw2v
      responses:
        "200":
          description: Invoice retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'

# ── COMPONENTS ─────────────────────────────────────────────────

components:

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic Auth. Pass your API key as the username, leave the 
        password empty.

  parameters:
    SubscriptionId:
      name: subscription_id
      in: path
      required: true
      description: Unique identifier for the subscription. Prefix `sub_`.
      schema:
        type: string
      example: sub_HxKtL3QmVr9p

  schemas:

    SubscriptionStatus:
      type: string
      enum:
        - future
        - in_trial
        - active
        - non_renewing
        - paused
        - cancelled
      description: |
        The subscription's current state in the lifecycle.

        | Status | Description |
        |---|---|
        | `future` | Created but start date is in the future. |
        | `in_trial` | Within the trial period. No charge yet. |
        | `active` | Billing normally. Renews at `current_term_end`. |
        | `non_renewing` | Scheduled to cancel at `current_term_end`. |
        | `paused` | Billing paused. Resumes at `resume_date`. |
        | `cancelled` | Terminated. No further billing. |

    InvoiceStatus:
      type: string
      enum:
        - paid
        - posted
        - payment_due
        - not_paid
        - voided
        - pending
      description: |
        | Status | Description |
        |---|---|
        | `paid` | Payment collected. |
        | `posted` | Issued but not yet due. |
        | `payment_due` | Due but not yet collected. |
        | `not_paid` | Collection failed after dunning. |
        | `voided` | Cancelled. Excluded from revenue. |
        | `pending` | Draft — line items still being added. |

    Subscription:
      type: object
      description: |
        Represents an ongoing billing relationship between a customer and 
        a plan. Subscriptions drive invoice generation, renewal, and 
        access control.
      properties:
        id:
          type: string
          description: Unique identifier. Prefix `sub_`.
          example: sub_HxKtL3QmVr9p
        customer_id:
          type: string
          description: ID of the customer this subscription belongs to.
          example: cus_KmQ9xT4pRw2v
        plan_id:
          type: string
          description: ID of the plan the customer is subscribed to.
          example: plan_pro_monthly
        status:
          $ref: '#/components/schemas/SubscriptionStatus'
        plan_quantity:
          type: integer
          description: Number of plan units. Relevant for per-seat plans.
          example: 5
        current_term_start:
          type: integer
          description: Unix timestamp for the start of the current billing term.
          example: 1704067200
        current_term_end:
          type: integer
          description: |
            Unix timestamp for the end of the current billing term. 
            An invoice is generated at this time unless the subscription 
            is in `non_renewing` or `cancelled` status.
          example: 1706745600
        trial_start:
          type: integer
          nullable: true
          description: Unix timestamp for trial start. `null` if no trial.
          example: null
        trial_end:
          type: integer
          nullable: true
          description: Unix timestamp for trial end. `null` if no trial.
          example: null
        cancelled_at:
          type: integer
          nullable: true
          description: Unix timestamp of cancellation. `null` if active.
        currency_code:
          type: string
          description: ISO 4217 currency code.
          example: USD
        created_at:
          type: integer
          description: Unix timestamp of subscription creation.
          example: 1704067200
        updated_at:
          type: integer
          description: Unix timestamp of last update.
          example: 1704153600
        metadata:
          type: object
          nullable: true
          description: |
            Key-value store for your own data. Up to 20 keys. 
            Values must be strings.
          additionalProperties:
            type: string

    Invoice:
      type: object
      description: |
        Represents a finalized billing event. Created automatically at 
        renewal or manually via the API. Invoices cannot be deleted — 
        only voided.

        > **Tip:** Voided invoices are excluded from MRR and ARR 
        > calculations. Always filter `status != voided` for revenue 
        > reporting.
      properties:
        id:
          type: string
          description: Unique identifier. Prefix `inv_`.
          example: inv_KmQ9xT4pRw2v
        customer_id:
          type: string
          example: cus_KmQ9xT4pRw2v
        subscription_id:
          type: string
          nullable: true
          description: |
            ID of the related subscription. `null` for one-off invoices.
          example: sub_HxKtL3QmVr9p
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        amount_due:
          type: integer
          description: |
            Total amount due, in the smallest currency unit (cents for USD).
            Use `currency_code` to format for display.
          example: 4900
        amount_paid:
          type: integer
          description: Amount already collected, in smallest currency unit.
          example: 4900
        amount_adjusted:
          type: integer
          description: Total credits or adjustments applied.
          example: 0
        currency_code:
          type: string
          example: USD
        due_date:
          type: integer
          nullable: true
          description: |
            Unix timestamp for payment due date. `null` for 
            immediate-payment invoices.
        line_items:
          type: array
          description: Individual charges making up the invoice total.
          items:
            type: object
            properties:
              id:
                type: string
                example: li_HxKtL3QmVr9p
              description:
                type: string
                example: Pro Plan — Jan 2024
              unit_amount:
                type: integer
                example: 4900
              quantity:
                type: integer
                example: 1
              amount:
                type: integer
                example: 4900
              entity_type:
                type: string
                enum: [plan, addon, adhoc, plan_item_price, addon_item_price]
        created_at:
          type: integer
          example: 1704067200
        updated_at:
          type: integer
          example: 1704153600

    Customer:
      type: object
      description: |
        A customer record stores billing identity, contact info, and 
        payment methods. One customer can have multiple subscriptions.
      properties:
        id:
          type: string
          description: Unique identifier. Prefix `cus_`.
          example: cus_KmQ9xT4pRw2v
        email:
          type: string
          format: email
          example: dev@example.com
        first_name:
          type: string
          nullable: true
          example: Alex
        last_name:
          type: string
          nullable: true
          example: Rivera
        company:
          type: string
          nullable: true
          example: Acme Corp
        auto_collection:
          type: string
          enum: [on, off]
          description: |
            Whether Chargebee automatically collects payment for this 
            customer's invoices. Can be overridden per subscription.
        created_at:
          type: integer
          example: 1704067200

    Error:
      type: object
      description: Error response body returned for all 4xx and 5xx responses.
      properties:
        api_error_code:
          type: string
          description: Machine-readable error code. Use this for programmatic handling.
          example: resource_not_found
        message:
          type: string
          description: Human-readable error message. Do not parse for logic.
          example: Subscription sub_HxKtL3QmVr9p not found.
        error_code:
          type: integer
          description: Chargebee internal error code. For support reference.
          example: 104
        http_status_code:
          type: integer
          description: HTTP status code.
          example: 404
        type:
          type: string
          enum: [payment, operation, invalid_request, io_exception]

  responses:
    BadRequest:
      description: |
        The request was malformed or missing required parameters. 
        Check `api_error_code` and `message` for specifics.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            api_error_code: param_missing
            message: "Required parameter missing: plan_id"
            error_code: 100
            http_status_code: 400
            type: invalid_request

    Unauthorized:
      description: |
        Authentication failed. Verify your API key is correct and 
        scoped to the right site (test vs. live).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            api_error_code: api_authentication_failed
            message: API key is invalid or does not match the site.
            error_code: 10000
            http_status_code: 401
            type: operation

    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            api_error_code: resource_not_found
            message: Subscription sub_HxKtL3QmVr9p not found.
            error_code: 104
            http_status_code: 404
            type: operation

security:
  - basicAuth: []