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

# Creating Credit Notes

> Interactive playground for creating credit notes (refunds) for sale transactions

# Creating Credit Notes

## Overview

Credit notes represent refunds, returns, or adjustments to original transactions. They maintain accurate sales records by reducing taxable amounts when refunds occur, ensuring your tax filings reflect net sales (sales minus refunds) rather than gross sales.

<Warning>
  You must have the Kintsugi transaction ID (not external\_id) of the original transaction to create a credit note. Store transaction IDs after creating transactions for future credit note creation.
</Warning>

## When to Create Credit Notes

* **Full refunds**: When a customer returns an entire order
* **Partial refunds**: When a customer returns specific items
* **Order cancellations**: When an order is cancelled after payment
* **Price adjustments**: When correcting pricing errors

## Prerequisites

Before creating a credit note, you need:

1. The original transaction must exist in Kintsugi
2. The original transaction must have status "COMMITTED"
3. The Kintsugi transaction ID (not the external\_id)

## Workflow

1. **Find Original Transaction** - Retrieve the original transaction to get its Kintsugi ID
2. **Create Credit Note** - Create a credit note linked to the original transaction
3. **Retrieve Credit Notes** - Verify the credit note was created

## Step 1: Find Original Transaction

If you don't have the Kintsugi transaction ID, find it using:

* `GET /v1/transactions/external/{external_id}` - Find by your external ID
* `GET /v1/transactions` - Search transactions and find the ID

## Step 2: Create Credit Note

Create a credit note using the interactive playground below with `POST /v1/transactions/{original_transaction_id}/credit_notes`.

### Required Fields

* `original_transaction_id`: The Kintsugi transaction ID (path parameter)
* `external_id`: Your internal credit note identifier
* `date`: Credit note date
* `currency`: Currency code (should match original transaction)
* `total_amount`: Refund amount (negative or positive)
* `type`: Transaction type (typically "FULL\_CREDIT\_NOTE" or "PARTIAL\_CREDIT\_NOTE")
* `status`: Transaction status (use "COMMITTED")
* `transaction_items`: Array of refunded line items

### Example Request

```json theme={null}
{
  "external_id": "CREDIT-001",
  "date": "2024-01-20T10:00:00Z",
  "currency": "USD",
  "total_amount": -100.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "FULL_CREDIT_NOTE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Example Product",
      "quantity": "1.0",
      "amount": -100.00
    }
  ]
}
```

## Step 3: Retrieve Credit Notes

Credit notes appear in transaction queries. Use `GET /v1/transactions` with:

* `transaction_type`: Filter by "FULL\_CREDIT\_NOTE" or "PARTIAL\_CREDIT\_NOTE"
* `related_to`: Filter by original transaction ID
* `search_query`: Search by credit note external\_id

## Authentication

This endpoint requires two headers:

* `x-api-key`: Your API key
* `x-organization-id`: Your organization ID

<Note>
  Both headers are required for authentication. You can find your API key and organization ID in your [Kintsugi dashboard](https://app.trykintsugi.com).
</Note>

## Try It Out

Use the interactive playground below to create a credit note. Replace `{original_transaction_id}` in the path with an actual transaction ID from your account.

<Info>
  The playground prefills example values from the API schema. You'll need to provide a valid transaction ID from your account.
</Info>

## Common Use Cases

### Full Refund

Create a credit note for a full refund:

```json theme={null}
{
  "external_id": "REFUND-001",
  "date": "2024-01-20T10:00:00Z",
  "currency": "USD",
  "total_amount": -150.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "FULL_CREDIT_NOTE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Product A",
      "quantity": "1.0",
      "amount": -100.00
    },
    {
      "external_id": "ITEM-002",
      "external_product_id": "PROD-002",
      "product": "Product B",
      "quantity": "1.0",
      "amount": -50.00
    }
  ]
}
```

### Partial Refund

Create a credit note for a partial refund:

```json theme={null}
{
  "external_id": "REFUND-002",
  "date": "2024-01-20T10:00:00Z",
  "currency": "USD",
  "total_amount": -50.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "PARTIAL_CREDIT_NOTE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Product A",
      "quantity": "1.0",
      "amount": -50.00
    }
  ]
}
```

## Response Fields

The API returns detailed credit note information:

* `id`: Kintsugi's unique credit note identifier
* `external_id`: Your credit note identifier
* `related_to`: Link to the original transaction ID
* `date`: Credit note date
* `total_amount`: Refund amount
* `type`: Credit note type (FULL\_CREDIT\_NOTE, PARTIAL\_CREDIT\_NOTE)
* `status`: Transaction status

## Next Steps

* [Get Transactions](/reference/api/transactions/get-transactions) - List and search credit notes
* [Update Credit Note](/reference/api/transactions/update-credit-note-by-transaction-id) - Modify credit note details
* [Handling Refund Transactions](/docs/api-guides/handling-refund-transactions) - Learn more about credit notes

## Related Resources

* [Create Credit Note API Reference](/reference/api/transactions/create-credit-note-by-transaction-id)
* [Getting Started](/docs/getting-started)
* [Support](https://trykintsugi.com/support)


## OpenAPI

````yaml post /v1/transactions/{original_transaction_id}/credit_notes
openapi: 3.0.0
info:
  title: Tax Platform
  version: 1.0.0
servers:
  - url: https://api.trykintsugi.com
    description: Production API server URL
security: []
paths:
  /v1/transactions/{original_transaction_id}/credit_notes:
    post:
      tags:
        - Transactions
      summary: Create Credit Note By Transaction Id
      description: Create a new credit note for a specific transaction.
      operationId: POST_create_credit_note_by_transaction_id
      parameters:
        - name: original_transaction_id
          in: path
          required: true
          schema:
            type: string
            title: Original Transaction Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteCreate'
            example:
              external_id: CN-12345
              date: '2024-10-27T14:30:00Z'
              status: PENDING
              description: Refund for damaged product
              total_amount: 50
              external_customer_id: CUST-456
              currency: USD
              transaction_items:
                - external_id: ITEM-1
                  date: '2024-10-27T14:30:00Z'
                  external_product_id: PROD-ABC
                  quantity: 1
                  amount: 50
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
          CustomHeader: []
components:
  schemas:
    CreditNoteCreate:
      properties:
        external_id:
          type: string
          title: External Id
          description: Unique identifier for the credit note in the external system.
        date:
          type: string
          format: date-time
          title: Date
          description: Date when the credit note was issued or created.
        status:
          type: string
          enum:
            - PENDING
            - CANCELLED
            - COMMITTED
          title: Status
          description: Current state of the credit note in its lifecycle.
        description:
          description: Brief explanation or reason for issuing the credit note.
          type: string
        total_amount:
          description: >-
            Total monetary value of the credit note, including all items and
            taxes.
          type: number
        marketplace:
          description: >-
            Indicates whether this credit note is associated with a marketplace
            transaction.
          default: false
          type: boolean
        tax_amount_imported:
          description: >-
            Pre-calculated total tax amount for the entire credit note, if
            provided by the external system.
          type: number
        tax_rate_imported:
          description: >-
            Pre-calculated overall tax rate for the credit note, if provided by
            the external system.
          type: number
        taxable_amount:
          description: Total portion of the credit note amount subject to taxation.
          type: number
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: The currency used for all amounts in this credit note.
        addresses:
          description: >-
            A list of TransactionAddressBuilder objects or None if no addresses
            are provided. This field represents the addresses associated with
            the transaction.
          type: array
          items:
            $ref: '#/components/schemas/TransactionAddressBuilder'
        transaction_items:
          items:
            $ref: '#/components/schemas/CreditNoteItemCreateUpdate'
          type: array
          title: Transaction Items
          description: Detailed list of individual items included in this credit note.
      type: object
      required:
        - external_id
        - date
        - status
        - total_amount
        - currency
        - transaction_items
      title: CreditNoteCreate
    TransactionRead:
      properties:
        requires_exemption:
          $ref: '#/components/schemas/ExemptionRequired'
          description: Indicates if transaction requires tax exemption.
        organization_id:
          type: string
          title: Organization Id
          description: >-
            Unique identifier of the organization. This field is deprecated, and
            should no longer be used. The value is populated through the
            'x-organization-id' header.
          deprecated: true
        external_id:
          type: string
          minLength: 1
          title: External Id
          description: External identifier of the transaction.
        date:
          type: string
          format: date-time
          title: Date
          description: Transaction date and time
        shop_date:
          description: Transaction date in the shop's local timezone
          type: string
        shop_date_tz:
          description: Timezone of the shop
          type: string
        description:
          description: Description of the transaction.
          type: string
        refund_status:
          $ref: '#/components/schemas/TransactionRefundStatus'
          description: Status of refund, if applicable
        total_amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Total Amount
          description: Total amount of the transaction.
          default: '0.00'
        customer_id:
          description: Unique identifier of the customer.
          type: string
        marketplace:
          description: Indicates if transaction is marketplace-based.
          default: false
          type: boolean
        exempt:
          $ref: '#/components/schemas/TransactionExemptStatusEnum'
          description: Exemption status (e.g., NOT_EXEMPT)
          default: NOT_EXEMPT
        exemptions:
          description: List of exemptions applied (if any).
          type: array
          items:
            $ref: '#/components/schemas/Exemption'
        related_to:
          description: Related transaction identifier.
          type: string
        secondary_external_id:
          description: Secondary External Identifier.
          type: string
        secondary_source:
          description: Secondary source information
          type: string
        external_friendly_id:
          description: Friendly identifier of the original item.
          type: string
        total_tax_amount_imported:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Total Tax Amount Imported
          description: Imported tax amount.
          default: '0.00'
        tax_rate_imported:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)
          title: Tax Rate Imported
          description: Imported tax rate.
          default: '0.00'
        total_tax_amount_calculated:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Total Tax Amount Calculated
          description: Calculated tax amount.
          default: '0.00'
        tax_rate_calculated:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)
          title: Tax Rate Calculated
          description: Calculated tax rate.
          default: '0.00'
        total_tax_liability_amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Total Tax Liability Amount
          description: Total tax liability amount.
          default: '0.00'
        tax_liability_source:
          $ref: '#/components/schemas/TaxLiabilitySourceEnum'
          description: Source of tax liability.
        taxable_amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Taxable Amount
          description: Taxable amount.
          default: '0.00'
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: Currency code (ISO 4217, e.g., USD)
          default: USD
        locked:
          type: boolean
          title: Locked
          description: Transaction lock status.
          default: false
        source:
          $ref: '#/components/schemas/SourceEnum'
          description: Source platform (e.g., STRIPE)
          default: OTHER
        connection_id:
          description: Connection Identifier
          type: string
        filing_id:
          description: Filing identifier.
          type: string
        city:
          description: City of the transaction address.
          type: string
        county:
          description: County of the transaction address.
          type: string
        state:
          description: State of the transaction address.
          type: string
        country:
          $ref: '#/components/schemas/CountryCodeEnum'
          description: Country code (ISO Alpha-2).
        postal_code:
          description: Postal code of the transaction.
          type: string
        tax_id:
          description: >-
            Tax ID associated with the transaction. DEPRECATED: This field is
            only populated for QuickBooks integrations and will be removed in a
            future version.
          deprecated: true
          type: string
        status:
          $ref: '#/components/schemas/TransactionStatusEnum'
          description: Transaction status (e.g., COMMITTED)
          default: COMMITTED
        address_status:
          $ref: '#/components/schemas/AddressStatus'
          description: Address verification status (e.g., VERIFIED).
          default: UNVERIFIED
        processing_status:
          $ref: '#/components/schemas/ProcessingStatusEnum'
          description: Status of processing (e.g., ADDRESS_DONE)
          default: QUEUED
        destination_currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: Destination currency code (ISO 4217, e.g., USD)
        converted_total_amount:
          description: Converted total amount.
          type: string
        converted_total_tax_amount_imported:
          description: Converted imported tax amount.
          type: string
        converted_total_tax_amount_calculated:
          description: Converted calculated tax amount.
          type: string
        conversion_rate:
          description: Currency conversion rate.
          type: string
        converted_taxable_amount:
          description: Converted taxable amount.
          type: string
        converted_total_discount:
          description: Converted total discount amount.
          type: string
        converted_subtotal:
          description: Converted subtotal amount.
          type: string
        converted_total_tax_liability_amount:
          description: Converted total tax liability amount.
          type: string
        id:
          type: string
          title: Id
          description: The unique transaction identifier.
        addresses:
          items:
            $ref: '#/components/schemas/TransactionAddressRead-Output'
          type: array
          title: Addresses
          description: List of addresses associated.
        transaction_items:
          items:
            $ref: '#/components/schemas/TransactionItemRead'
          type: array
          title: Transaction Items
          description: List of items in the transaction.
        customer:
          $ref: '#/components/schemas/CustomerRead'
          description: Customer information associated with the transaction.
        type:
          $ref: '#/components/schemas/TransactionTypeEnum'
          description: |-
            The type of transaction
                                                (e.g., SALE, REFUND, PARTIAL_CREDIT_NOTE).
        total_discount:
          description: Total amount of all discounts applied to the transaction.
          type: string
        subtotal:
          description: Subtotal amount before any discounts are applied.
          type: string
        final_total_amount:
          description: Final total amount including tax liability.
          type: string
        converted_final_total_amount:
          description: Converted final total amount including tax liability.
          type: string
      type: object
      required:
        - organization_id
        - external_id
        - date
        - id
        - addresses
        - transaction_items
        - type
      title: TransactionRead
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CurrencyEnum:
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLP
        - CNY
        - COP
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GGP
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - IMP
        - INR
        - IQD
        - IRR
        - ISK
        - JEP
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SPL
        - SRD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TVD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VEF
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XDR
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
        - ZWD
      title: CurrencyEnum
    TransactionAddressBuilder:
      properties:
        phone:
          description: Phone number associated with the address.
          type: string
        street_1:
          description: Primary street address.
          type: string
        street_2:
          description: >-
            Additional street address details, such as an apartment or suite
            number.
          type: string
        city:
          description: City where the customer resides.
          type: string
        county:
          description: County or district of the customer.
          type: string
        state:
          description: State or province of the customer.
          type: string
        postal_code:
          description: ZIP or Postal code of the customer.
          type: string
        country:
          $ref: '#/components/schemas/CountryCodeEnum'
          description: Country code in ISO 3166-1 alpha-2 format
        full_address:
          description: >-
            Complete address string of the customer, which can be used as an
            alternative to individual fields.
          type: string
        type:
          $ref: '#/components/schemas/AddressType'
          description: 'Type of address. Allowed values: BILL_TO, SHIP_TO.'
        enriched_fields:
          description: Optional additional enriched data for the address.
          type: string
        status:
          $ref: '#/components/schemas/AddressStatus'
          description: >-
            Address verification status.** This field is ignored when updating
            addresses. The status of the address is updated automatically. **
          default: UNVERIFIED
        organization_id:
          type: string
      type: object
      required:
        - type
      title: TransactionAddressBuilder
    CreditNoteItemCreateUpdate:
      properties:
        external_id:
          type: string
          title: External Id
          description: Unique identifier for the credit note item in the external system.
        date:
          type: string
          format: date-time
          title: Date
          description: Date when the credit note item was issued or created.
        description:
          description: Brief explanation or details about the credit note item.
          type: string
        external_product_id:
          type: string
          title: External Product Id
          description: Unique identifier for the associated product in the external system.
        quantity:
          description: Number of units or amount of the product being credited.
          type: number
        amount:
          description: Total monetary value of the credit note item before taxes.
          type: number
        tax_amount_imported:
          description: >-
            Pre-calculated tax amount for the item, if provided by the external
            system.
          type: number
        tax_rate_imported:
          description: >-
            Pre-calculated tax rate for the item, if provided by the external
            system.
          type: number
        taxable_amount:
          description: Portion of the item amount subject to taxation.
          type: number
        tax_exemption:
          $ref: '#/components/schemas/TaxExemptionEnum'
          description: Specific tax exemption status applied to this item, if any.
        tax_items:
          items:
            $ref: '#/components/schemas/TaxItemBuilder'
          type: array
          title: Tax Items
          description: >-
            Detailed breakdown of individual tax components applied to this
            item.
          default: []
      type: object
      required:
        - external_id
        - date
        - external_product_id
        - quantity
        - amount
      title: CreditNoteItemCreateUpdate
    ExemptionRequired:
      properties:
        jurisdiction:
          type: string
        customer_id:
          type: string
        organization_id:
          type: string
          title: Organization Id
          description: >-
            Unique identifier of the organization. This field is deprecated, and
            should no longer be used. The value is populated through the
            'x-organization-id' header.
          deprecated: true
        exemption_type:
          $ref: '#/components/schemas/ExemptionType'
        start_date:
          type: string
          format: date-time
          title: Start Date
        status:
          $ref: '#/components/schemas/ExemptionStatus'
        reseller:
          type: boolean
          title: Reseller
      type: object
      required:
        - organization_id
        - exemption_type
        - start_date
        - status
        - reseller
      title: ExemptionRequired
    TransactionRefundStatus:
      type: string
      enum:
        - FULLY_REFUNDED
        - PARTIALLY_REFUNDED
      title: TransactionRefundStatus
      description: >-
        Shopify has 2 order statuses for refund case: refunded and
        partially_refunded

        If the given order has different status from these 2, we will set the

        transaction's refund_status to PARTIALLY_REFUNDED by default.
    TransactionExemptStatusEnum:
      type: string
      enum:
        - NOT_EXEMPT
        - PARTIALLY_EXEMPT
        - FULLY_EXEMPT
        - ZERO_RATE_NOT_EXEMPT
      title: TransactionExemptStatusEnum
      description: |-
        Based on transaction item exempt status.
        NOT EXEMPT: None of the items are NOT EXEMPT
        PARTIALLY EXEMPT: At least some of the items are NOT EXEMPT
        FULLY_EXEMPT: All items sold in the transaction are EXEMPT
        ZERO_RATE_NOT_EXEMPT: All items sold in the transaction are zero-rated
    Exemption:
      properties:
        id:
          type: string
          maxLength: 100
          title: Id
          description: Unique identifier for the exemption
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when transaction was created in Kintsugi.
        updated_at:
          description: Timestamp when transaction was last updated.
          type: string
        exemption_type:
          $ref: '#/components/schemas/ExemptionType'
          description: The type of exemption (e.g., wholesale, resale)
        jurisdiction:
          description: The jurisdiction identifier for the exemption
          type: string
        country_code:
          $ref: '#/components/schemas/CountryCodeEnum'
          description: Country code in ISO 3166-1 alpha-2 format (e.g., 'US')
        start_date:
          type: string
          format: date
          title: Start Date
          description: Start date for the exemption validity period (YYYY-MM-DD format)
        end_date:
          description: End date for the exemption validity period (YYYY-MM-DD format)
          type: string
        customer_id:
          description: Unique identifier for the customer associated with the exemption
          type: string
        transaction_id:
          description: |-
            Unique identifier for the transaction
                    associated with the exemption, if applicable.
          type: string
        reseller:
          type: boolean
          title: Reseller
          description: Indicates whether the exemption is for a reseller
          default: false
        FEIN:
          description: |-
            Federal Employer Identification Number
                    associated with the exemption.
          type: string
        sales_tax_id:
          description: Sales tax ID for the exemption
          type: string
        status:
          $ref: '#/components/schemas/ExemptionStatus'
          description: |-
            The status of the exemption.
                    Defaults to ACTIVE if not provided.
        organization_id:
          type: string
          maxLength: 100
          title: Organization Id
      type: object
      required:
        - exemption_type
        - start_date
      title: Exemption
    TaxLiabilitySourceEnum:
      type: string
      enum:
        - CALCULATED
        - COLLECTED
      title: TaxLiabilitySourceEnum
    SourceEnum:
      type: string
      enum:
        - BIGCOMMERCE
        - BESTBUY
        - BUNNY
        - CHARGEBEE
        - SHOPIFY
        - STRIPE
        - AMAZON
        - TIKTOK
        - CUSTOM
        - UNKNOWN
        - IMPORT
        - ZUORA
        - APIDECK
        - QUICKBOOKS
        - API
        - APPLE_APP_STORE
        - GOOGLE_APP_STORE
        - WALMART
        - PAYPAL
        - NETSUITE
        - XERO
        - MAXIO
        - RECURLY
        - SALESFORCE
        - ETSY
        - EBAY
        - WIX
        - SQUARESPACE
        - WOOCOMMERCE
        - MAGENTO
        - BILLING_PLATFORM
        - DEEL
        - RIPPLING
        - GUSTO
        - FACEBOOK
        - OTHER
        - ORDWAY
        - INSTAGRAM
        - PINTEREST
        - WAYFAIR
        - WISH
        - POS
        - TARGET
        - NEWEGG
        - GROUPON
        - GOOGLE_EXPRESS
        - NOCNOC
        - MERCADO_LIBRE
        - MODALYST
        - NORDSTROM
        - FAIRE
        - SHOPWARE
        - ZOHO
        - SAGE-INTACCT
        - AIRWALLEX
        - ORB
        - ZENSKAR
        - MICROSOFT_DYNAMICS_365
        - KICKSTARTER
        - INTERNAL_ERP
      title: SourceEnum
    CountryCodeEnum:
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - CV
        - KH
        - CM
        - CA
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - SZ
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - CI
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MK
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
        - XK
        - ZZ_EU
      title: CountryCodeEnum
    TransactionStatusEnum:
      type: string
      enum:
        - PENDING
        - COMMITTED
        - CANCELLED
        - FULLY_REFUNDED
        - PARTIALLY_REFUNDED
        - INVALID
        - ARCHIVED
      title: TransactionStatusEnum
    AddressStatus:
      type: string
      enum:
        - UNVERIFIED
        - INVALID
        - PARTIALLY_VERIFIED
        - VERIFIED
        - UNVERIFIABLE
        - BLANK
      title: AddressStatus
    ProcessingStatusEnum:
      type: string
      enum:
        - NEW
        - UPDATED
        - QUEUED
        - ADDRESS_DONE
        - EXEMPT_DONE
        - NEXUS_DONE
        - PROCESSED
        - FILING_STARTED
        - FILING_DONE
        - LOCKED
        - PENDING
        - ARCHIVED
        - NEEDS_REFETCH
        - EXCLUDED_IN_CALCULATION
      title: ProcessingStatusEnum
      description: >-
        Our transaction state, used to determine when/if a transaction needs
        additional

        processing.
    TransactionAddressRead-Output:
      properties:
        phone:
          description: Phone number associated with the address.
          type: string
        street_1:
          description: Primary street address.
          type: string
        street_2:
          description: >-
            Additional street address details, such as an apartment or suite
            number.
          type: string
        city:
          description: City where the customer resides.
          type: string
        county:
          description: County or district of the customer.
          type: string
        state:
          description: State or province of the customer.
          type: string
        postal_code:
          description: ZIP or Postal code of the customer.
          type: string
        country:
          $ref: '#/components/schemas/CountryCodeEnum'
          description: Country code in ISO 3166-1 alpha-2 format
        full_address:
          description: >-
            Complete address string of the customer, which can be used as an
            alternative to individual fields.
          type: string
        type:
          $ref: '#/components/schemas/AddressType'
          description: 'Type of address. Allowed values: BILL_TO, SHIP_TO.'
        status:
          $ref: '#/components/schemas/AddressStatus'
          description: >-
            Address verification status.** This field is ignored when updating
            addresses. The status of the address is updated automatically. **
          default: UNVERIFIED
        id:
          description: Unique identifier of the address being updated.
          type: string
        transaction_id:
          description: ID of the transaction associated with the address.
          type: string
        connection_id:
          description: ID of the connection associated with the address.
          type: string
      type: object
      required:
        - type
      title: TransactionAddressRead
    TransactionItemRead:
      properties:
        external_id:
          description: External item identifier.
          type: string
        organization_id:
          description: >-
            Unique identifier of the organization. This field is deprecated, and
            should no longer be used. The value is populated through the
            'x-organization-id' header.
          deprecated: true
          type: string
        date:
          type: string
          format: date-time
          title: Date
          description: Date/time of item.
        description:
          description: Item description
          type: string
        external_product_id:
          type: string
          title: External Product Id
          description: External product identifier.
        product:
          description: Product name
          type: string
        product_id:
          description: Product identifier.
          type: string
        product_name:
          description: Product name (detailed)
          type: string
        product_description:
          description: Product description
          type: string
        quantity:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,20}|(?=[\d.]{1,41}0*$)\d{0,20}\.\d{0,20}0*$)
          title: Quantity
          description: Quantity of item.
          default: '1.0'
        amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Amount
          description: Item amount.
          default: '0.00'
        tax_amount_imported:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Tax Amount Imported
          description: Imported tax amount for the item.
          default: '0.00'
        tax_rate_imported:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)
          title: Tax Rate Imported
          description: Imported tax rate.
          default: '0.00'
        tax_amount_calculated:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Tax Amount Calculated
          description: Calculated tax amount for the item.
          default: '0.00'
        tax_rate_calculated:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)
          title: Tax Rate Calculated
          description: Calculated tax rate.
          default: '0.00'
        original_currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: Original currency code.
        destination_currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: Destination currency code.
        converted_amount:
          description: Converted item amount.
          type: string
        converted_taxable_amount:
          description: Converted taxable amount.
          type: string
        converted_tax_amount_imported:
          description: Converted imported tax amount.
          type: string
        converted_tax_amount_calculated:
          description: Converted calculated tax amount
          type: string
        converted_total_discount:
          description: Converted total discount amount.
          type: string
        converted_subtotal:
          description: Converted subtotal amount.
          type: string
        taxable_amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Taxable Amount
          description: Taxable amount for the item.
          default: '0.00'
        tax_exemption:
          $ref: '#/components/schemas/TaxExemptionEnum'
          description: Tax exemption status.
        exempt:
          type: boolean
          title: Exempt
          description: Indicates if the item is exempt.
          default: false
        id:
          type: string
          title: Id
          description: The unique transaction item identifier.
        tax_items:
          items:
            $ref: '#/components/schemas/TaxItemRead'
          type: array
          title: Tax Items
          description: List of tax items associated with the transaction item.
        total_discount:
          description: Total discount amount applied to this transaction item.
          type: string
        subtotal:
          description: Subtotal amount before any discount is applied.
          type: string
      type: object
      required:
        - organization_id
        - date
        - external_product_id
        - id
        - tax_items
      title: TransactionItemRead
    CustomerRead:
      properties:
        phone:
          description: Customer's phone number
          type: string
        street_1:
          description: Primary street address.
          type: string
        street_2:
          description: >-
            Additional street address details, such as an apartment or suite
            number.
          type: string
        city:
          description: City where the customer resides.
          type: string
        county:
          description: County or district of the customer.
          type: string
        state:
          description: State or province of the customer.
          type: string
        postal_code:
          description: ZIP or Postal code of the customer.
          type: string
        country:
          $ref: '#/components/schemas/CountryCodeEnum'
          description: Country code in ISO 3166-1 alpha-2 format
        full_address:
          description: >-
            Complete address string of the customer, which can be used as an
            alternative to individual fields.
          type: string
        name:
          description: Name of the customer.
          type: string
        external_id:
          description: External identifier associated with the customer.
          type: string
        status:
          $ref: '#/components/schemas/StatusEnum'
          description: Status of the customer.
          default: ACTIVE
        email:
          description: Customer's email address
          type: string
        source:
          $ref: '#/components/schemas/SourceEnum'
          description: Source of the customer's record.
        connection_id:
          description: Identifier for the connection source, if applicable.
          type: string
        address_status:
          $ref: '#/components/schemas/AddressStatus'
          description: Status of address verification
          default: UNVERIFIED
        registration_number:
          description: Registration number of the customer.
          type: string
        external_friendly_id:
          description: >-
            External friendly identifier associated with the customer. We need
            it for netsuite.
          type: string
        customer_tax_registrations:
          items:
            $ref: '#/components/schemas/CustomerTaxRegistrationRead'
          type: array
          title: Customer Tax Registrations
          description: Customer tax registrations associated with the customer.
        id:
          type: string
          title: Id
          description: Unique identifier for the customer required.
        organization_id:
          type: string
          title: Organization Id
          description: >-
            Unique identifier for the organization associated with the customer.
            Required.
      type: object
      required:
        - id
        - organization_id
      title: CustomerRead
    TransactionTypeEnum:
      type: string
      enum:
        - SALE
        - FULL_CREDIT_NOTE
        - PARTIAL_CREDIT_NOTE
        - TAX_REFUND
        - ARCHIVE
      title: TransactionTypeEnum
    ValidationError:
      properties:
        loc:
          items:
            type: string
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AddressType:
      type: string
      enum:
        - BILL_TO
        - SHIP_TO
        - SHIP_FROM
        - BILL_FROM
      title: AddressType
    TaxExemptionEnum:
      type: string
      enum:
        - PRODUCT
        - TRANSACTION
        - CUSTOMER
        - REGION
        - REVERSE_CHARGE
        - ZERO_RATE_TAX
        - HIGH_VALUE_PHYSICAL_GOODS
        - EXPORT
        - ZERO_VALUE_ITEM
        - NO_RULE_FOUND
        - IMPORTED
        - ZERO_RATE_NOT_EXEMPT
      title: TaxExemptionEnum
      description: This enum is used to determine if a transaction is exempt from tax.
    TaxItemBuilder:
      properties:
        rule_id:
          type: string
          title: Rule Id
          description: The rule ID of the tax item
          default: '0000'
        rate:
          type: number
        amount:
          type: number
        converted_amount:
          type: number
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
        destination_currency:
          $ref: '#/components/schemas/CurrencyEnum'
        external_id:
          type: string
        name:
          type: string
          maxLength: 250
          title: Name
          description: 'Deprecated: use `jurisdiction_type` instead'
        type:
          $ref: '#/components/schemas/TaxItemTypeEnum'
          maxLength: 50
          default: IMPORTED
        jurisdiction_type:
          $ref: '#/components/schemas/JurisdictionType'
        jurisdiction_name:
          type: string
        organization_id:
          type: string
      type: object
      required:
        - rate
        - amount
        - name
        - organization_id
      title: TaxItemBuilder
    ExemptionType:
      type: string
      enum:
        - customer
        - wholesale
        - transaction
      title: ExemptionType
    ExemptionStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - EXPIRED
        - DEACTIVATED
        - ARCHIVED
      title: ExemptionStatus
    TaxItemRead:
      properties:
        rule_id:
          type: string
          title: Rule Id
          description: The rule ID of the tax item
          default: '0000'
        rate:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)
          title: Rate
        amount:
          type: string
          pattern: >-
            ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
          title: Amount
        converted_amount:
          type: string
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
        destination_currency:
          $ref: '#/components/schemas/CurrencyEnum'
        external_id:
          type: string
        name:
          type: string
          maxLength: 250
          title: Name
          description: 'Deprecated: use `jurisdiction_type` instead'
        type:
          $ref: '#/components/schemas/TaxItemTypeEnum'
          maxLength: 50
          default: IMPORTED
        jurisdiction_type:
          $ref: '#/components/schemas/JurisdictionType'
        jurisdiction_name:
          type: string
      type: object
      required:
        - rate
        - amount
        - name
      title: TaxItemRead
    StatusEnum:
      type: string
      enum:
        - ACTIVE
        - ARCHIVED
      title: StatusEnum
    CustomerTaxRegistrationRead:
      properties:
        id:
          type: string
          title: Id
        customer_id:
          type: string
          title: Customer Id
        country_code:
          $ref: '#/components/schemas/CountryCodeEnum'
        tax_type:
          $ref: '#/components/schemas/CustomerTaxTypeEnum'
        tax_id:
          type: string
          title: Tax Id
        is_valid:
          type: boolean
          title: Is Valid
      type: object
      required:
        - id
        - customer_id
        - country_code
        - tax_type
        - tax_id
        - is_valid
      title: CustomerTaxRegistrationRead
    TaxItemTypeEnum:
      type: string
      enum:
        - IMPORTED_ORIGINAL
        - IMPORTED
        - CALCULATED
      title: TaxItemTypeEnum
    JurisdictionType:
      type: string
      enum:
        - COUNTRY
        - FEDERAL
        - STATE
        - COUNTY
        - CITY
        - SPECIAL
        - OTHER
        - HYBRID
      title: JurisdictionType
    CustomerTaxTypeEnum:
      type: string
      enum:
        - gst
        - hst
        - gst_hst
        - qst
        - pst
        - rst
        - vat
        - unknown
      title: CustomerTaxTypeEnum
      description: Enum for customer tax registration types.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
    CustomHeader:
      type: apiKey
      in: header
      name: x-organization-id

````