Schematic

Schematic billing API

The billing API from Schematic — 17 operation(s) for billing.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.schematichq.com/
📖
APIReference
https://docs.schematichq.com/api-reference
📖
Authentication
https://docs.schematichq.com/api-reference/authentication.mdx
📖
GettingStarted
https://docs.schematichq.com/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/openapi/schematic-billing-api-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/SchematicHQ

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/json-schema/schematic-company-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/json-schema/schematic-feature-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/json-schema/schematic-plan-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/json-structure/schematic-api-structure.json

Other Resources

🔗
SDK Python
https://github.com/SchematicHQ/schematic-python
🔗
SDK Node
https://github.com/SchematicHQ/schematic-node
🔗
SDK Go
https://github.com/SchematicHQ/schematic-go
🔗
SDK Ruby
https://github.com/SchematicHQ/schematic-ruby
🔗
SDK Java
https://github.com/SchematicHQ/schematic-java
🔗
SDK PHP
https://github.com/SchematicHQ/schematic-php
🔗
SDK C#
https://github.com/SchematicHQ/schematic-csharp
🔗
SpectralRules
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/rules/schematic-rules.yml
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/json-ld/schematic-context.jsonld

OpenAPI Specification

schematic-billing-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  title: Schematic accesstokens billing API
  version: '0.1'
  description: Schematic API
  x-rules-engine-schema-version: v97288f60
servers:
- url: https://api.schematichq.com
security:
- ApiKeyAuth: []
tags:
- name: billing
paths:
  /billing/coupons:
    get:
      operationId: listCoupons
      summary: List coupons
      tags:
      - billing
      parameters:
      - name: is_active
        in: query
        schema:
          type: boolean
      - name: q
        in: query
        schema:
          type: string
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingCouponResponseData'
                    title: ListCouponsResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      is_active:
                        type: boolean
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      q:
                        type: string
                    title: ListCouponsParams
                required:
                - data
                - params
                title: ListCouponsResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      operationId: upsertBillingCoupon
      summary: Upsert billing coupon
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCouponRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingCouponResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertBillingCouponParams
                required:
                - data
                - params
                title: UpsertBillingCouponResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/customer/upsert:
    post:
      operationId: upsertBillingCustomer
      summary: Upsert billing customer
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingCustomerRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingCustomerResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertBillingCustomerParams
                required:
                - data
                - params
                title: UpsertBillingCustomerResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/customers:
    get:
      operationId: listCustomersWithSubscriptions
      summary: List customers with subscriptions
      tags:
      - billing
      parameters:
      - name: company_ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: name
        in: query
        schema:
          type: string
          maxLength: 255
      - name: provider_type
        in: query
        schema:
          $ref: '#/components/schemas/BillingProviderType'
      - name: q
        in: query
        schema:
          type: string
          maxLength: 512
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingCustomerWithSubscriptionsResponseData'
                    title: ListCustomersWithSubscriptionsResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_ids:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      name:
                        type: string
                        maxLength: 255
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      provider_type:
                        $ref: '#/components/schemas/BillingProviderType'
                      q:
                        type: string
                        maxLength: 512
                    title: ListCustomersWithSubscriptionsParams
                required:
                - data
                - params
                title: ListCustomersWithSubscriptionsResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/customers/count:
    get:
      operationId: countCustomers
      summary: Count customers
      tags:
      - billing
      parameters:
      - name: company_ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: name
        in: query
        schema:
          type: string
          maxLength: 255
      - name: provider_type
        in: query
        schema:
          $ref: '#/components/schemas/BillingProviderType'
      - name: q
        in: query
        schema:
          type: string
          maxLength: 512
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CountResponse'
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_ids:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      name:
                        type: string
                        maxLength: 255
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      provider_type:
                        $ref: '#/components/schemas/BillingProviderType'
                      q:
                        type: string
                        maxLength: 512
                    title: CountCustomersParams
                required:
                - data
                - params
                title: CountCustomersResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/invoices:
    get:
      operationId: listInvoices
      summary: List invoices
      tags:
      - billing
      parameters:
      - name: company_id
        in: query
        schema:
          type: string
      - name: customer_external_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 255
      - name: subscription_external_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 255
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoiceResponseData'
                    title: ListInvoicesResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_id:
                        type: string
                      customer_external_id:
                        type: string
                        maxLength: 255
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      subscription_external_id:
                        type: string
                        maxLength: 255
                    title: ListInvoicesParams
                required:
                - data
                - params
                title: ListInvoicesResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      operationId: upsertInvoice
      summary: Upsert invoice
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InvoiceResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertInvoiceParams
                required:
                - data
                - params
                title: UpsertInvoiceResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/meter:
    get:
      operationId: listMeters
      summary: List meters
      tags:
      - billing
      parameters:
      - name: display_name
        in: query
        schema:
          type: string
          maxLength: 255
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingMeterResponseData'
                    title: ListMetersResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      display_name:
                        type: string
                        maxLength: 255
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                    title: ListMetersParams
                required:
                - data
                - params
                title: ListMetersResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/meter/upsert:
    post:
      operationId: upsertBillingMeter
      summary: Upsert billing meter
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMeterRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingMeterResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertBillingMeterParams
                required:
                - data
                - params
                title: UpsertBillingMeterResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/payment-methods:
    get:
      operationId: listPaymentMethods
      summary: List payment methods
      tags:
      - billing
      parameters:
      - name: company_id
        in: query
        schema:
          type: string
      - name: customer_external_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 255
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethodResponseData'
                    title: ListPaymentMethodsResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_id:
                        type: string
                      customer_external_id:
                        type: string
                        maxLength: 255
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                    title: ListPaymentMethodsParams
                required:
                - data
                - params
                title: ListPaymentMethodsResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      operationId: upsertPaymentMethod
      summary: Upsert payment method
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentMethodRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentMethodResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertPaymentMethodParams
                required:
                - data
                - params
                title: UpsertPaymentMethodResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/price:
    get:
      operationId: listBillingPrices
      summary: List billing prices
      tags:
      - billing
      parameters:
      - name: currency
        in: query
        description: Filter for prices in a specific currency (e.g. usd, eur)
        schema:
          type: string
          description: Filter for prices in a specific currency (e.g. usd, eur)
          maxLength: 3
      - name: for_initial_plan
        in: query
        description: Filter for prices valid for initial plans (free prices only)
        schema:
          type: boolean
          description: Filter for prices valid for initial plans (free prices only)
      - name: for_trial_expiry_plan
        in: query
        description: Filter for prices valid for trial expiry plans (free prices only)
        schema:
          type: boolean
          description: Filter for prices valid for trial expiry plans (free prices only)
      - name: ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: interval
        in: query
        schema:
          type: string
          maxLength: 255
      - name: is_active
        in: query
        description: Filter for active prices on active products (defaults to true if not specified)
        schema:
          type: boolean
          description: Filter for active prices on active products (defaults to true if not specified)
      - name: price
        in: query
        schema:
          type: integer
          format: int64
      - name: product_id
        in: query
        schema:
          type: string
      - name: product_ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: provider_type
        in: query
        schema:
          $ref: '#/components/schemas/BillingProviderType'
      - name: q
        in: query
        schema:
          type: string
      - name: tiers_mode
        in: query
        schema:
          $ref: '#/components/schemas/BillingTiersMode'
      - name: usage_type
        in: query
        schema:
          $ref: '#/components/schemas/BillingPriceUsageType'
      - name: with_meter
        in: query
        description: Filter for prices with a meter
        schema:
          type: boolean
          description: Filter for prices with a meter
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingPriceView'
                    title: ListBillingPricesResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      currency:
                        type: string
                        description: Filter for prices in a specific currency (e.g. usd, eur)
                        maxLength: 3
                      for_initial_plan:
                        type: boolean
                        description: Filter for prices valid for initial plans (free prices only)
                      for_trial_expiry_plan:
                        type: boolean
                        description: Filter for prices valid for trial expiry plans (free prices only)
                      ids:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      interval:
                        type: string
                        maxLength: 255
                      is_active:
                        type: boolean
                        description: Filter for active prices on active products (defaults to true if not specified)
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      price:
                        type: integer
                        format: int64
                      product_id:
                        type: string
                      product_ids:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      provider_type:
                        $ref: '#/components/schemas/BillingProviderType'
                      q:
                        type: string
                      tiers_mode:
                        $ref: '#/components/schemas/BillingTiersMode'
                      usage_type:
                        $ref: '#/components/schemas/BillingPriceUsageType'
                      with_meter:
                        type: boolean
                        description: Filter for prices with a meter
                    title: ListBillingPricesParams
                required:
                - data
                - params
                title: ListBillingPricesResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/price/upsert:
    post:
      operationId: upsertBillingPrice
      summary: Upsert billing price
      tags:
      - billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingPriceRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingPriceResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertBillingPriceParams
                required:
                - data
                - params
                title: UpsertBillingPriceResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/product/{billing_id}:
    delete:
      operationId: deleteBillingProduct
      summary: Delete billing product
      tags:
      - billing
      parameters:
      - name: billing_id
        in: path
        description: billing_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DeleteResponse'
                  params:
                    type: object
                    description: Input parameters
                    title: DeleteBillingProductParams
                required:
                - data
                - params
                title: DeleteBillingProductResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /billing/product/prices:
    get:
      operationId: listBillingProductPrices
      summary: List billing product prices
      tags:
      - billing
      parameters:
      - name: currency
        in: query
        description: Filter for prices in a specific currency (e.g. usd, eur)
        schema:
          type: string
          description: Filter for prices in a specific currency (e.g. usd, eur)
          maxLength: 3
      - name: for_initial_plan
        in: query
        description: Filter for prices valid for initial plans (free prices only)
        schema:
          type: boolean
          description: Filter for prices valid for initial plans (free prices only)
      - name: for_trial_expiry_plan
        in: query
        description: Filter for prices valid for trial expiry plans (free prices only)
        schema:
          type: boolean
          description: Filter for prices valid for trial expiry plans (free prices only)
      - name: ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: interval
        in: query
        schema:
          type: string
          maxLength: 255
      - name: is_active
        in: query
        description: Filter for active prices on active products (defaults to true if not specified)
        schema:
          type: boolean
          description: Filter for active prices on active products (defaults to true if not specified)
      - name: price
        in: query
        schema:
          type: integer
          format: int64
      - name: product_id
        in: query
        schema:
          type: string
      - name: product_ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: provider_type
        in: query
        schema:
          $ref: '#/components/schemas/BillingProviderType'


# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/openapi/schematic-billing-api-openapi.yml