> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nocotax.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Billing Schedule

> Creates a Billing Schedule.



## OpenAPI

````yaml /api-reference/openapi.yaml post /billing_schedules
openapi: 3.0.1
info:
  title: Nocotax API
  version: v1
servers:
  - url: https://api.nocotax.app/
    variables:
      protocol:
        default: https
      defaultHost:
        default: api.nocotax.app/
security:
  - basic_auth: []
tags:
  - name: Introduction
    x-traitTag: true
    description: >
      The Nocotax API is organized around REST. Our API is designed to have 

      predictable, resource-oriented URLs and to use HTTP response codes to 

      indicate API errors. We use built-in HTTP features, like HTTP verbs, 

      which can be understood by off-the-shelf HTTP clients.


      JSON will be returned in all responses from the API, including errors.


      To make the Nocotax API as secure as possible. Authentication is
      performed 

      through HTTP Basic Auth. Credentials can be found on your Nocotax 

      developers menu, in the "API Keys" section.
  - name: Authentication
    x-traitTag: true
    description: >
      Authentication to the API occurs via HTTP Basic Auth.

      Provide your Account ID as the basic auth username, and the API secret key
      as the password.


      All API requests must be made over HTTPS. Calls made over plain HTTP will
      fail.

      You must authenticate for all requests.


      You can manage your API keys from your account.

      Your API keys carry many privileges, so be sure to keep them secret!
  - name: Errors
    x-traitTag: true
    description: >
      Nocotax uses conventional HTTP response codes to indicate success or
      failure of an API request.


      In general, codes in the 2xx range indicate success,

      codes in the 4xx range indicate an error that resulted from the provided
      information

      (e.g. a required parameter was missing), and codes in the 5xx range
      indicate an error with our servers.


      ```
        HTTP status codes summary
        
        200 OK - Everything worked as expected.
        201 Created - Resource has been successfully created
        202 Accepted - Request has been accepted, but requires asynchronous work to be fully performed

        400 Bad Request - Request failed due to a combination of errors
        401 Unauthorized - No valid API credentials provided.
        402 Payment Required - Your request was in livemode while your account is not activated for live requests yet.
        403 Forbidden - You are not authorized to access the requested item.
        404 Not Found - The requested item doesn't exist.
        406 Unacceptable - Your request format was not supported. Use JSON.
        409 Conflict - The data you submitted is in conflict with existing data.
        422 Unprocessable Entity - Often missing a required parameter.
        429 Too Many Requests - You sent us too many API requests in a row. Please retry later.
        
        500, 502, 503, 504 Server errors - something went wrong on our end.
      ```
  - name: Pagination
    x-traitTag: true
    description: >
      All top-level API resources have support for bulk fetches “list” API
      methods.

      For instance, you can list organization, list invoices.


      We use cursor-based pagination using the parameter `after`.

      Pass `after` parameter at the previous page last object id value to
      determine where to start in the list.


      Reverse pagination is possible as well thanks to the `before` parameter.


      ## Attributes

      <table>
        <tr><th>Attribute</th><th>Type</th></tr>
        <tr><td><strong>limit</strong></td><td>integer, optional A limit on the number of objects to be returned. Must be included between 1 and 100</td>
        <tr><td><strong>after</strong></td><td>string, optional A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `after=obj_foo` in order to fetch the next page of the list.</td>
        <tr><td><strong>before</strong></td><td>string, optional A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `before=obj_bar` in order to fetch the previous page of the list.</td>
      </table>


      ### List Response format

      <table>
        <tr><th>Attribute</th><th>Type</th></tr>
        <tr><td><strong>object</strong></td><td>string, value is `list`</td></tr>
        <tr><td><strong>data</strong></td><td>array, An array containing the actual response elements, paginated by any request parameters.</td></tr>
        <tr><td><strong>has_before</strong></td><td>boolean, Whether or not there are more elements available before this page. If `false`, this page is the beginning of the list.</td></tr>
        <tr><td><strong>has_more</strong></td><td>boolean, Whether or not there are more elements available after this page. If `false`, this page is the end of the list</td></tr>
      </table>
paths:
  /billing_schedules:
    post:
      tags:
        - Billing Schedules
      summary: Create a Billing Schedule
      description: Creates a Billing Schedule.
      operationId: BillingSchedulesCreate
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                billing_cycle_id:
                  type: string
                  description: >-
                    The ID of the `billing_cycle` this `billing_schedule` refers
                    to. It will inherit from its recurring/on_demand data
                    (period, and days of exeution). Leave empty if you want to
                    select the default `billing_cycle` for the selected `flow`
                    (see below).
                  nullable: true
                customer_id:
                  type: string
                  description: >-
                    The ID of the organization that is invoiced through this
                    billing schedule. Do not include in payload if
                    `flow=PURCHASES`.
                  nullable: true
                flow:
                  type: string
                  description: >-
                    `COMMISSIONS`: Representing an aggregation of commissions
                    between your organization and a recipient (seller).
                    `PURCHASES`: Representing a recurring (or on-demand) self
                    billing flow between a supplier and your organization
                  enum:
                    - COMMISSIONS
                    - PURCHASES
                supplier_id:
                  type: string
                  description: >-
                    The ID of the organization that is the supplier of invoices
                    through this billing schedule. Do not include in payload if
                    `flow=COMMISSIONS`.
                  nullable: true
              required:
                - flow
      responses:
        '201':
          description: successful
          content:
            application/json:
              example:
                id: bs_1792060726bq4j472a038e
                livemode: false
                object: billing_schedule
                billing_cycle:
                  id: bc_1792060725ey4515069adc
                  livemode: false
                  object: billing_cycle
                  is_default: true
                  flow: COMMISSIONS
                  period: MONTHLY
                  period_day: 8
                  period_weekday: null
                  created_at: '2026-10-15T10:38:45.702Z'
                  updated_at: '2026-10-15T10:38:45.702Z'
                billing_cycle_id: bc_1792060725ey4515069adc
                cancelled_at: null
                customer:
                  id: org_1792060725ebpca4104a50
                  livemode: false
                  object: organization
                  billing_address:
                    city: Legroschester
                    line1: 7571 Truman View
                    line2: Apt. 372
                    country: AX
                    postal_code: 92280-2844
                  business_registration_number: '85285027000392'
                  contact_information: {}
                  is_professional: true
                  name: Schaden-Hayes
                  ownership: external
                  roles:
                    - MERCHANT
                  timezone: Etc/UTC
                  tax_identification_number: '246571418'
                  created_at: '2026-10-15T10:38:45.674Z'
                  updated_at: '2026-10-15T10:38:45.674Z'
                  billing_address_formatted: |-
                    7571 Truman View
                    Apt. 372
                    Legroschester  92280-2844
                    Åland Islands
                  tax_registrations:
                    - id: txr_1792060725ehiqfd740ee5
                      livemode: false
                      object: tax_registration
                      country: FR
                      options: null
                      organization_id: org_1792060725ebpca4104a50
                      tax_id: eu-vat
                      number: FR76906873427
                      type: standard
                      zone: EU
                      created_at: '2026-10-15T10:38:45.685Z'
                      updated_at: '2026-10-15T10:38:45.685Z'
                      tax:
                        id: eu-vat
                        name: VAT
                        display_name: VAT
                        zone: EU
                        jurisdictions: []
                customer_id: org_1792060725ebpca4104a50
                flow: COMMISSIONS
                last_billed_at: null
                next_billing_date: '2026-11-08T05:00:00.000Z'
                next_billing_period_end: '2026-11-08T05:00:00.000Z'
                next_billing_period_start: '2026-10-15T10:38:46.558Z'
                status: active
                supplier_id: org_1792060725cxyf38d4c17a
                created_at: '2026-10-15T10:38:46.560Z'
                updated_at: '2026-10-15T10:38:46.560Z'
              schema:
                $ref: '#/components/schemas/billingSchedule'
        default:
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    billingSchedule:
      type: object
      description: |2-

                      A billing schedule represents recurring generation of invoices between your platform and another entity.
                      Each schedule is timezone-aware and executes at the specified time in the account's local timezone, based on its `billing_cycle` details.
                      A billing schedule can represent two types of billing:
                      * Self-billing: Between a supplier (supplier_id) and the account's self-owned organization
                      * Commission billing: Between the account's self-owned organization and a recipient (customer_id)
                    
      properties:
        id:
          type: string
        livemode:
          type: boolean
        object:
          type: string
        billing_cycle_id:
          type: string
          description: The ID of the `billing_cycle` this `billing_schedule` is linked to.
        cancelled_at:
          type: string
          format: date-time
          description: >-
            In case of a cancellation of the schedule, the datetime to which it
            has been deleted
          nullable: true
        customer_id:
          type: string
          description: >-
            The ID of the organization that is invoiced through this billing
            schedule
        flow:
          type: string
          description: >-
            `COMMISSIONS`: Representing an aggregation of commissions between
            your organization and a recipient (seller). `PURCHASES`:
            Representing a recurring (or on-demand) self billing flow between a
            supplier and your organization
          enum:
            - COMMISSIONS
            - PURCHASES
        last_billed_at:
          type: string
          format: date-time
          description: The last time this billing schedule has been run
          nullable: true
        next_billing_date:
          type: string
          format: date-time
          description: >-
            The next occurrence this billing schedule will run. `null` if the
            underlying billing cycle period is `ON_DEMAND`
        status:
          type: string
          description: >-
            The status of this `billing_schedule`. `active`: Is active.
            `cancelled`: has been cancelled
          enum:
            - active
            - cancelled
        supplier_id:
          type: string
          description: >-
            The ID of the organization that is the supplier of invoices through
            this billing schedule
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    errorResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
        type:
          type: string
          enum:
            - INVALID_REQUEST_ERROR
        params:
          nullable: true
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              errors:
                type: array
                items:
                  type: string
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.