openapi: 3.0.0
info:
  version: '1'
  title: Kinde Account API Keys Billing Agreements API
  description: '

    Provides endpoints to operate on an authenticated user.


    ## Intro


    ## How to use


    1. Get a user access token - this can be obtained when a user signs in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc).


    2. Call one of the endpoints below using the user access token in the Authorization header as a Bearer token. Typically, you can use the `getToken` command in the relevant SDK.

    '
  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
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\n\n<div>\n  <code>read:billing_agreements</code>\n</div>\n"
      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
          nullable: true
      - name: starting_after
        in: query
        required: false
        description: The ID of the billing agreement to start after.
        schema:
          type: string
          nullable: true
      - name: ending_before
        in: query
        required: false
        description: The ID of the billing agreement to end before.
        schema:
          type: string
          nullable: true
      - name: customer_id
        in: query
        description: The ID of the billing customer to retrieve agreements for
        required: true
        schema:
          type: string
          nullable: false
        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
          nullable: true
      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\n\n<div>\n  <code>create:billing_agreements</code>\n</div>\n"
      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:
  responses:
    bad_request:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    forbidden:
      description: Unauthorized - invalid credentials.
      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'
  schemas:
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
    success_response:
      type: object
      properties:
        message:
          type: string
          example: Success
        code:
          type: string
          example: OK
    error_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    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
  securitySchemes:
    kindeBearerAuth:
      description: 'To access these endpoints, you will need to use a user token. This can be obtained when your users sign in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc). Find this using the getToken command in the relevant SDK.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT