> ## 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 Credit Note

> Creates a credit note.



## OpenAPI

````yaml /api-reference/openapi.yaml post /credit_notes
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:
  /credit_notes:
    post:
      tags:
        - Credit Notes
      summary: Create a Credit Note
      description: Creates a credit note.
      operationId: CreditNotesCreate
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                automatic_tax_calculation:
                  type: object
                  description: >-
                    Defaults to `false`. When automatic tax calculation is
                    enabled, Nocotax automatically determines which tax rates
                    must be applied to each item sold within the document. 
                    Nocotax also determines which tax registrations to apply on
                    this document
                  properties:
                    enabled:
                      type: boolean
                      description: >-
                        Whether automatic tax calculation is enabled for the
                        current document or not
                  nullable: true
                currency:
                  type: string
                  description: The currency ISO code of the document
                customer_id:
                  type: string
                  description: >-
                    The ID of the organization this document refers as a
                    customer.  Required if `flow` is not `purchases`
                customer_tax_registration_ids:
                  type: array
                  description: >-
                    The customer’s tax registration IDs, that will be displayed
                    on PDFs. Not compatible with
                    `automatic_tax_calculation[enabled]=true`.
                  items:
                    type: string
                  nullable: true
                invoice_id:
                  type: string
                  nullable: true
                  description: >-
                    If this credit note refers to an invoice, the ID of this
                    invoice.
                items:
                  type: array
                  description: A list of max. 10 line items to be added to the credit note.
                  nullable: true
                  items:
                    type: object
                    properties:
                      extratax_amount:
                        type: integer
                        description: >-
                          The extratax amount of the item, in the currency's
                          smaller unit (eg. cents).
                        nullable: true
                      product:
                        type: object
                        properties:
                          tax_code:
                            type: string
                            description: >-
                              The tax code of the product or service sold.
                              Useful for tax calculations. Defaults to:
                              `D10000000`.
                        nullable: true
                      title:
                        type: string
                        description: >-
                          A short description of the product/item sold. Will
                          appear on documents
                      quantity:
                        type: number
                        format: float
                        description: >-
                          A decimal representation of the quantity sold.
                          Defaults to 1.
                        nullable: true
                      tax_included_amount:
                        type: integer
                        description: >-
                          The amount including taxes of the item, in the
                          currency's smaller unit (eg. cents).
                        nullable: true
                      period:
                        type: object
                        description: >-
                          The period associated with this item, if different
                          than parent document. Used to recognize and defer
                          revenue
                        nullable: true
                        properties:
                          end:
                            type: string
                            description: Must be greater than or equal to the start
                            format: date-time
                          start:
                            type: string
                            format: date-time
                        required:
                          - start
                          - end
                      taxes:
                        type: array
                        description: >-
                          A list of taxes that applies to the current item. Not
                          compatible with
                          `automatic_tax_calculation[enabled]=true`.
                        nullable: true
                        items:
                          type: object
                          properties:
                            jurisdiction:
                              type: string
                              description: The jurisdiction this tax amount refers to
                              nullable: true
                            percentage:
                              type: string
                              format: decimal
                              nullable: true
                            tax_id:
                              type: string
                              description: ID of the `tax` object this tax amount refers to
                            tax_exemption:
                              type: object
                              description: >-
                                When filled, the reason why this amount is tax
                                exempt
                              nullable: true
                              properties:
                                type:
                                  type: string
                                  description: >-
                                    Enum representing why this amount is tax
                                    exempt
                                legal_notice:
                                  type: string
                                  description: >-
                                    A piece of text to be displayed on document
                                    representations justifying the tax
                                    exemption.
                      unit_extratax_amount:
                        type: string
                        format: decimal
                        description: >-
                          The unit amount excluding taxes of the item, formatted
                          as a decimal (up to 12 decimal places). If provided,
                          it will be multiplied by the quantity to get the full
                          amount.
                        nullable: true
                      unit_tax_included_amount:
                        type: string
                        format: decimal
                        description: >-
                          The unit amount including taxes of the item, formatted
                          as a decimal (up to 12 decimal places). If provided,
                          it will be multiplied by the quantity to get the full
                          amount.
                        nullable: true
                issuer:
                  type: object
                  description: >-
                    If the issuer of the document is not the supplier (in case
                    of white-label or self billing), information on the issuer
                  nullable: true
                  properties:
                    type:
                      type: string
                      enum:
                        - CUSTOMER
                      description: >-
                        `CUSTOMER`: For self-billing purposes. The customer is
                        the issuer of the credit note
                flow:
                  type: string
                  enum:
                    - sales
                    - purchases
                    - platform
                  description: >
                    Specifies the direction or role of the account owner in the
                    invoicing transaction.

                    `sales`: The account owner is the supplier (i.e., the entity
                    issuing the document for goods or services provided).

                    `purchases`: The account owner is the customer (i.e., the
                    entity receiving the document for goods or services
                    purchased).

                    `platform`: The account owner is a facilitator (i.e., the
                    entity enabling the transaction between a customer and a
                    supplier, such as a marketplace or intermediary).
                locale:
                  type: string
                  description: The locale used for this credit note representations (PDF)
                  nullable: true
                memo:
                  type: string
                  description: Document memo
                  nullable: true
                numbering_sequence_id:
                  type: string
                  description: >-
                    The ID of the numbering sequence this document is using to
                    generate its number at finalization. Fallbacks to default
                    for organization if not provided
                  nullable: true
                order_reference:
                  type: string
                  nullable: true
                period:
                  type: object
                  description: >-
                    The period associated with this document. Used to recognize
                    and defer revenue
                  nullable: true
                  properties:
                    end:
                      type: string
                      description: Must be greater than or equal to the start
                      format: date-time
                    start:
                      type: string
                      format: date-time
                  required:
                    - start
                    - end
                supplier_id:
                  type: string
                  description: >-
                    The ID of the organization this document refers as a
                    supplier. Required if `flow` is not `sales`
                supplier_tax_registration_ids:
                  type: array
                  description: >-
                    The supplier's tax registration IDs, that will be displayed
                    on PDFs. Not compatible with
                    `automatic_tax_calculation[enabled]=true`.
                  items:
                    type: string
                  nullable: true
              required:
                - currency
                - flow
      responses:
        '201':
          description: successful
          content:
            application/json:
              example:
                id: cn_17920607414fecd28c4674
                livemode: false
                object: credit_note
                amount_to_credit: null
                amount_overcredited: null
                amount_credited: null
                amount_post_payment: null
                amount_pre_payment: null
                amount_remaining: null
                automatic_tax_calculation:
                  enabled: true
                credit_status: null
                currency: EUR
                customer_data:
                  name: Kunde-Dietrich
                  billing_address:
                    city: Mariettashire
                    line1: 9428 Reichert Garden
                    line2: Apt. 712
                    country: 'NO'
                    postal_code: 61470-9968
                  business_registration_number: '23205436100802'
                  tax_identification_number: '468336193'
                customer_id: org_179206074069vh2a00cf6b
                customer_tax_registration_data: []
                customer_tax_registration_ids: []
                document_date: null
                document_number: null
                flow: sales
                invoice_id: null
                issuer: null
                legal_notices: null
                locale: en
                memo: null
                metadata: {}
                numbering_sequence_id: ns_179206074064nifa543c82
                order_reference: null
                period: null
                representations: {}
                status: draft
                status_transitions: {}
                supplier_country: TJ
                supplier_data:
                  name: Hettinger, Bashirian and Hermann
                  billing_address:
                    city: Lake Antoniahaven
                    line1: 4088 Noe Forest
                    line2: Apt. 635
                    country: TJ
                    postal_code: 89312-6170
                  business_registration_number: '60260274000014'
                  tax_identification_number: '959328808'
                supplier_id: org_17920607405xhyb2e87bad
                supplier_tax_registration_data: []
                supplier_tax_registration_ids: []
                taxes:
                  - tax_id: no-vat
                    percentage: '0.0'
                    jurisdiction: 'NO'
                    tax_exemption:
                      type: NOT_REGISTERED
                      legal_notice: null
                    taxable_amount: 4374684
                total_extratax_amount: 4374684
                total_tax_amount: 0
                total_tax_included_amount: 4374684
                created_at: '2026-10-15T10:39:01.215Z'
                updated_at: '2026-10-15T10:39:01.215Z'
              schema:
                $ref: '#/components/schemas/creditNote'
        default:
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    creditNote:
      type: object
      properties:
        id:
          type: string
        livemode:
          type: boolean
        object:
          type: string
        amount_to_credit:
          type: integer
          description: >-
            The amount to credit at the time the credit note is finalized, in
            the currency's smaller unit (eg. cents)
          nullable: true
        amount_overcredited:
          type: integer
          description: >-
            If the amount of transactions attached to this credit note exceed
            its amount to credit, the amount overcredited, in the currency's
            smaller unit (eg. cents)
          nullable: true
        amount_credited:
          type: integer
          description: >-
            The amount that has been credited, in the currency's smaller unit
            (eg. cents)
          nullable: true
        amount_post_payment:
          type: integer
          description: The amount that will need to be credited to the customer
          nullable: true
        amount_pre_payment:
          type: integer
          description: >-
            If attached to an invoice, the amount by which the corresponding
            invoice `amount_remaining` is reduced
          nullable: true
        amount_remaining:
          type: integer
          description: >-
            The amount still to credit, in the currency's smaller unit (eg.
            cents)
          nullable: true
        automatic_tax_calculation:
          type: object
          description: >-
            When automatic tax calculation is enabled, Nocotax automatically
            determines which tax rates must be applied to each item sold within
            the document.
          properties:
            enabled:
              type: boolean
              description: >-
                Whether automatic tax calculation is enabled for the current
                document or not
        credit_status:
          type: string
          enum:
            - to_credit
            - credited
          description: >-
            The credit status of the credit note. `to_credit`: The credit note
            has an amount that needs to be credited to the customer. `credited`:
            This credit note has been totally credited to the customer.
          nullable: true
        currency:
          type: string
          description: The currency ISO code of the document
        customer_data:
          type: object
          properties:
            billing_address:
              type: object
              properties:
                recipient:
                  type: string
                  nullable: true
                line1:
                  type: string
                  nullable: true
                line2:
                  type: string
                  nullable: true
                city:
                  type: string
                  nullable: true
                postal_code:
                  type: string
                  nullable: true
                state:
                  type: string
                  nullable: true
                country:
                  type: string
            business_registration_number:
              type: string
              nullable: true
            name:
              type: string
            tax_identification_number:
              type: string
              nullable: true
        customer_id:
          type: string
          description: The ID of the organization this document refers as a customer
        customer_tax_registration_data:
          type: array
          description: >-
            The customer’s tax registration data. They are displayed on the PDF
            of the document, and may be used for automatic tax calculation if
            enabled.
          items:
            type: object
            properties:
              country:
                type: string
              number:
                type: string
              tax_id:
                type: string
              tax_registration_type:
                type: string
        customer_tax_registration_ids:
          type: array
          description: The customer’s tax registration IDs.
          items:
            type: string
        document_date:
          type: string
          description: >-
            The date of issuance of this document. Its value is `null` when the
            document status is `draft`
          nullable: true
        document_number:
          type: string
          description: >-
            The number of this document. Its value is `null` when the document
            status is `draft`
          nullable: true
        issuer:
          type: object
          description: >-
            If the issuer of the document is not the supplier (in case of
            white-label or self billing), information on the issuer
          nullable: true
          properties:
            type:
              type: string
              enum:
                - CUSTOMER
              description: >-
                `CUSTOMER`: For self-billing purposes. The customer is the
                issuer of the credit note
        flow:
          type: string
          enum:
            - sales
            - purchases
            - platform
          description: >
            Specifies the direction or role of the account owner in the
            invoicing transaction.

            `sales`: The account owner is the supplier (i.e., the entity issuing
            the document for goods or services provided).

            `purchases`: The account owner is the customer (i.e., the entity
            receiving the document for goods or services purchased).

            `platform`: The account owner is a facilitator (i.e., the entity
            enabling the transaction between a customer and a supplier, such as
            a marketplace or intermediary).
        invoice_id:
          type: string
          nullable: true
          description: If this credit note refers to an invoice, the ID of this invoice.
        legal_notices:
          type: array
          nullable: true
          items:
            type: string
            description: >-
              A text representing a legal notice to display on document
              representations
        locale:
          type: string
          description: The locale used for this credit note representations (PDF)
        memo:
          type: string
          description: Document memo
          nullable: true
        numbering_sequence_id:
          type: string
          description: >-
            The ID of the numbering sequence this document is using to generate
            its number at finalization
        order_reference:
          type: string
          nullable: true
        period:
          type: object
          description: >-
            The period associated with this document. Used to recognize and
            defer revenue
          properties:
            end:
              type: string
              description: Must be greater than or equal to the start
              format: date-time
            start:
              type: string
              format: date-time
          nullable: true
        representations:
          type: object
          description: >-
            After finalization of a document, you can share its representations
            to whoever you want. This is a set of URLs you can share.
          properties:
            hosted_page_url:
              type: string
              description: A link to a hosted page that customers and suppliers can use
            pdf_file_url:
              type: string
              description: The link to download the PDF
        status:
          type: string
          enum:
            - draft
            - finalized
            - cancelled
          description: The status of the document, one of `draft`, `finalized`, `cancelled`
        status_transitions:
          type: object
          properties:
            finalized_at:
              type: string
              format: date-time
              nullable: true
        supplier_country:
          type: string
          description: The country (ISO alpha 2) of the country of issuance of the document
        supplier_data:
          type: object
          properties:
            billing_address:
              type: object
              properties:
                recipient:
                  type: string
                  nullable: true
                line1:
                  type: string
                  nullable: true
                line2:
                  type: string
                  nullable: true
                city:
                  type: string
                  nullable: true
                postal_code:
                  type: string
                  nullable: true
                state:
                  type: string
                  nullable: true
                country:
                  type: string
            business_registration_number:
              type: string
              nullable: true
            name:
              type: string
            tax_identification_number:
              type: string
              nullable: true
        supplier_id:
          type: string
          description: The ID of the organization this document refers as a supplier
        supplier_tax_registration_data:
          type: array
          description: >-
            The supplier's tax registration data. They are displayed on the PDF
            of the document, and may be used for automatic tax calculation if
            enabled.
          items:
            type: object
            properties:
              country:
                type: string
              number:
                type: string
              tax_id:
                type: string
              tax_registration_type:
                type: string
        supplier_tax_registration_ids:
          type: array
          description: The customer’s tax registration IDs.
          items:
            type: string
        taxes:
          type: array
          description: The document's tax breakdown
          nullable: true
          items:
            type: object
            properties:
              jurisdiction:
                type: string
                description: The jurisdiction this tax amount refers to
                nullable: true
              percentage:
                type: string
                format: decimal
                description: ''
                nullable: true
              tax_id:
                type: string
                description: ID of the `tax` object this tax amount refers to
                nullable: true
              tax_exemption:
                type: object
                description: When filled, the reason why this amount is tax exempt
                nullable: true
                properties:
                  type:
                    type: string
                    description: Enum representing why this amount is tax exempt
                  legal_notice:
                    type: string
                    description: >-
                      A piece of text to be displayed on document
                      representations justifying the tax exemption.
                    nullable: true
              taxable_amount:
                type: integer
                description: >-
                  The amount, in the currency's smaller unit (eg. cents), this
                  tax applies upon
        total_extratax_amount:
          type: integer
          description: >-
            Total extratax amount of the document, in the currency's smaller
            unit (eg. cents)
        total_tax_amount:
          type: integer
          description: >-
            Total tax amount of the document, in the currency's smaller unit
            (eg. cents)
        total_tax_included_amount:
          type: integer
          description: >-
            Total tax included of the document, in the currency's smaller unit
            (eg. cents)
        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.