Kinde Billing Agreements API

openapi: 3.2.0
info:
  version: '1'
  title: Kinde Management Billing Agreements API
  description: 'Provides endpoints to manage your Kinde Businesses.


    ## Intro


    ## How to use


    1. Set up and authorize a machine-to-machine (M2M) application.


    2. Generate a test access token


    3. Test request any endpoint using the test token'
  termsOfService: https://docs.kinde.com/trust-center/agreements/terms-of-service/
  contact:
    name: Kinde Support Team
    email: support@kinde.com
    url: https://docs.kinde.com
servers:
- url: https://{subdomain}.kinde.com
  variables:
    subdomain:
      default: your_kinde_subdomain
      description: The subdomain generated for your business on Kinde.
tags:
- name: Billing Agreements
  x-displayName: Billing Agreements
paths:
  /api/v1/billing/agreements:
    servers: []
    get:
      tags:
      - Billing Agreements
      operationId: getBillingAgreements
      description: 'Returns all the agreements a billing customer currently has access to


        read:billing_agreements'
      summary: Get billing agreements
      parameters:
      - name: page_size
        in: query
        required: false
        description: Number of results per page. Defaults to 10 if parameter not sent.
        schema:
          type:
          - integer
          - 'null'
      - name: starting_after
        in: query
        required: false
        description: The ID of the billing agreement to start after.
        schema:
          type:
          - string
          - 'null'
      - name: ending_before
        in: query
        required: false
        description: The ID of the billing agreement to end before.
        schema:
          type:
          - string
          - 'null'
      - name: customer_id
        in: query
        description: The ID of the billing customer to retrieve agreements for
        required: true
        schema:
          type: string
        example: customer_0195ac80a14c2ca2cec97d026d864de0
      - name: feature_code
        in: query
        required: false
        description: The feature code to filter by agreements only containing that feature
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: Billing agreements successfully retrieved.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/get_billing_agreements_response'
            application/json:
              schema:
                $ref: '#/components/schemas/get_billing_agreements_response'
        '400':
          description: Invalid request.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/error_response'
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '403':
          description: Invalid credentials.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/error_response'
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '429':
          description: Request was throttled.
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Billing Agreements
      operationId: createBillingAgreement
      description: 'Creates a new billing agreement based on the plan code passed, and cancels the customer''s existing agreements


        create:billing_agreements'
      summary: Create billing agreement
      requestBody:
        description: New agreement request values
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_id
              - plan_code
              properties:
                customer_id:
                  description: The ID of the billing customer to create a new agreement for
                  type: string
                  example: customer_0195ac80a14c2ca2cec97d026d864de0
                plan_code:
                  description: The code of the billing plan the new agreement will be based on
                  type: string
                  example: pro
                is_invoice_now:
                  type: boolean
                  description: Generate a final invoice for any un-invoiced metered usage.
                  example: true
                is_prorate:
                  type: boolean
                  description: Generate a proration invoice item that credits remaining unused features.
                  example: true
      responses:
        '200':
          description: Billing agreement successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
components:
  schemas:
    error_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    success_response:
      type: object
      properties:
        message:
          type: string
          example: Success
        code:
          type: string
          example: OK
    get_billing_agreements_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        has_more:
          description: Whether more records exist.
          type: boolean
        agreements:
          type: array
          description: A list of billing agreements
          items:
            type: object
            properties:
              id:
                type: string
                description: The friendly id of an agreement
                example: agreement_0195ac80a14c2ca2cec97d026d864de0
              plan_code:
                type: string
                description: The plan code the billing customer is subscribed to
              expires_on:
                type: string
                format: date-time
                description: The date the agreement expired (and was no longer active)
                example: '2024-11-18T13:32:03+11'
              billing_group_id:
                type: string
                description: The friendly id of the billing group this agreement's plan is part of
                example: sbg_0195abf6773fdae18d5da72281a3fde2
              entitlements:
                type: array
                description: A list of billing entitlements that is part of this agreement
                items:
                  type: object
                  properties:
                    feature_code:
                      type: string
                      description: The feature code of the feature corresponding to this entitlement
                      example: CcdkvEXpbg6UY
                    entitlement_id:
                      type: string
                      description: The friendly id of an entitlement
                      example: entitlement_0195ac80a14e8d71f42b98e75d3c61ad
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
  responses:
    bad_request:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    too_many_requests:
      description: Too many requests. Request was throttled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    forbidden:
      description: Unauthorized - invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  securitySchemes:
    kindeBearerAuth:
      description: 'Requires an access token obtained using the client_credentials flow.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT