openapi: 3.1.0
info:
  title: Chargebee API v2
  version: "2"
  description: |
    REST API for Chargebee subscription billing covering customers,
    subscriptions, invoices, payments, and product catalog. Authenticates with
    HTTP Basic Auth using a site-scoped API key as the username and an empty
    password. Authoritative OpenAPI spec is published at
    https://github.com/chargebee/openapi (see /spec).
  contact:
    name: Chargebee API Support
    url: https://www.chargebee.com/docs/api
servers:
  - url: https://{site}.chargebee.com/api/v2
    description: Site-scoped Chargebee API base URL
    variables:
      site:
        default: yoursite
        description: Your Chargebee site subdomain
security:
  - basicAuth: []
tags:
  - name: Customers
  - name: Subscriptions
  - name: Invoices
  - name: Payments
  - name: Plans
  - name: Items
  - name: Orders
  - name: Quotes
paths:
  /customers:
    get:
      tags: [Customers]
      summary: List customers
      operationId: listCustomers
      parameters:
        - in: query
          name: limit
          schema: { type: integer, default: 10, maximum: 100 }
        - in: query
          name: offset
          schema: { type: string }
      responses:
        "200":
          description: List of customers
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CustomerList" }
    post:
      tags: [Customers]
      summary: Create a customer
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/CustomerCreate" }
      responses:
        "200":
          description: Customer created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CustomerEnvelope" }
  /customers/{customer_id}:
    parameters:
      - in: path
        name: customer_id
        required: true
        schema: { type: string }
    get:
      tags: [Customers]
      summary: Retrieve a customer
      operationId: retrieveCustomer
      responses:
        "200":
          description: Customer
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CustomerEnvelope" }
  /subscriptions:
    get:
      tags: [Subscriptions]
      summary: List subscriptions
      operationId: listSubscriptions
      responses:
        "200":
          description: List of subscriptions
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SubscriptionList" }
    post:
      tags: [Subscriptions]
      summary: Create a subscription for a customer
      operationId: createSubscription
      responses:
        "200":
          description: Subscription created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SubscriptionEnvelope" }
  /subscriptions/{subscription_id}:
    parameters:
      - in: path
        name: subscription_id
        required: true
        schema: { type: string }
    get:
      tags: [Subscriptions]
      summary: Retrieve a subscription
      operationId: retrieveSubscription
      responses:
        "200":
          description: Subscription
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SubscriptionEnvelope" }
  /invoices:
    get:
      tags: [Invoices]
      summary: List invoices
      operationId: listInvoices
      responses:
        "200":
          description: List of invoices
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InvoiceList" }
  /invoices/{invoice_id}:
    parameters:
      - in: path
        name: invoice_id
        required: true
        schema: { type: string }
    get:
      tags: [Invoices]
      summary: Retrieve an invoice
      operationId: retrieveInvoice
      responses:
        "200":
          description: Invoice
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InvoiceEnvelope" }
  /payments:
    get:
      tags: [Payments]
      summary: List payments
      operationId: listPayments
      responses:
        "200":
          description: List of payments
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenericList" }
  /plans:
    get:
      tags: [Plans]
      summary: List plans (Product Catalog v1)
      operationId: listPlans
      responses:
        "200":
          description: List of plans
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenericList" }
  /items:
    get:
      tags: [Items]
      summary: List items (Product Catalog v2)
      operationId: listItems
      responses:
        "200":
          description: List of items
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenericList" }
  /orders:
    get:
      tags: [Orders]
      summary: List orders
      operationId: listOrders
      responses:
        "200":
          description: List of orders
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenericList" }
  /quotes:
    get:
      tags: [Quotes]
      summary: List quotes
      operationId: listQuotes
      responses:
        "200":
          description: List of quotes
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenericList" }
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth. Username is your Chargebee site API key; password is empty.
  schemas:
    Customer:
      type: object
      properties:
        id: { type: string }
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        company: { type: string }
        created_at: { type: integer, format: int64 }
    CustomerCreate:
      type: object
      properties:
        id: { type: string }
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        company: { type: string }
    CustomerEnvelope:
      type: object
      properties:
        customer: { $ref: "#/components/schemas/Customer" }
    CustomerList:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
            properties:
              customer: { $ref: "#/components/schemas/Customer" }
        next_offset: { type: string }
    Subscription:
      type: object
      properties:
        id: { type: string }
        customer_id: { type: string }
        status: { type: string }
        plan_id: { type: string }
        currency_code: { type: string }
    SubscriptionEnvelope:
      type: object
      properties:
        subscription: { $ref: "#/components/schemas/Subscription" }
        customer: { $ref: "#/components/schemas/Customer" }
    SubscriptionList:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
            properties:
              subscription: { $ref: "#/components/schemas/Subscription" }
        next_offset: { type: string }
    Invoice:
      type: object
      properties:
        id: { type: string }
        customer_id: { type: string }
        status: { type: string }
        total: { type: integer }
        currency_code: { type: string }
    InvoiceEnvelope:
      type: object
      properties:
        invoice: { $ref: "#/components/schemas/Invoice" }
    InvoiceList:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
            properties:
              invoice: { $ref: "#/components/schemas/Invoice" }
        next_offset: { type: string }
    GenericList:
      type: object
      properties:
        list:
          type: array
          items: { type: object }
        next_offset: { type: string }