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.

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.

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:

The original transaction must exist in Kintsugi
The original transaction must have status “COMMITTED”
The Kintsugi transaction ID (not the external_id)

Workflow

Find Original Transaction - Retrieve the original transaction to get its Kintsugi ID
Create Credit Note - Create a credit note linked to the original transaction
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

{
  "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

Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

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.

The playground prefills example values from the API schema. You’ll need to provide a valid transaction ID from your account.

Common Use Cases

Full Refund

Create a credit note for a full refund:

{
  "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:

{
  "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 - List and search credit notes
Update Credit Note - Modify credit note details
Handling Refund Transactions - Learn more about credit notes

Authorizations

X-API-KEY

string

header

required

x-organization-id

string

header

required

Path Parameters

original_transaction_id

string

required

Body

application/json

external_id

string

required

Unique identifier for the credit note in the external system.

date

string<date-time>

required

Date when the credit note was issued or created.

status

enum<string>

required

Current state of the credit note in its lifecycle.

Available options:

PENDING,

CANCELLED,

COMMITTED

total_amount

number

required

Total monetary value of the credit note, including all items and taxes.

currency

enum<string>

required

The currency used for all amounts in this credit note.

Available options:

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

transaction_items

CreditNoteItemCreateUpdate · object[]

required

Detailed list of individual items included in this credit note.

Show child attributes

transaction_items.external_id

string

required

Unique identifier for the credit note item in the external system.

transaction_items.date

string<date-time>

required

Date when the credit note item was issued or created.

transaction_items.external_product_id

string

required

Unique identifier for the associated product in the external system.

transaction_items.quantity

number

required

Number of units or amount of the product being credited.

transaction_items.amount

number

required

Total monetary value of the credit note item before taxes.

transaction_items.description

string

Brief explanation or details about the credit note item.

transaction_items.tax_amount_imported

number

Pre-calculated tax amount for the item, if provided by the external system.

transaction_items.tax_rate_imported

number

Pre-calculated tax rate for the item, if provided by the external system.

transaction_items.taxable_amount

number

Portion of the item amount subject to taxation.

transaction_items.tax_exemption

enum<string>

Specific tax exemption status applied to this item, if any.

Available options:

PRODUCT,

TRANSACTION,

CUSTOMER,

REGION,

REVERSE_CHARGE,

ZERO_RATE_TAX,

HIGH_VALUE_PHYSICAL_GOODS,

EXPORT,

ZERO_VALUE_ITEM,

NO_RULE_FOUND,

IMPORTED

transaction_items.tax_items

TaxItemBuilder · object[]

Detailed breakdown of individual tax components applied to this item.

Show child attributes

transaction_items.tax_items.rate

number

required

transaction_items.tax_items.amount

number

required

transaction_items.tax_items.name

string

required

Deprecated: use jurisdiction_type instead

Maximum string length: 250

transaction_items.tax_items.organization_id

string

required

transaction_items.tax_items.rule_id

string

default:0000

The rule ID of the tax item

transaction_items.tax_items.converted_amount

number

transaction_items.tax_items.currency

enum<string>

Available options:

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

transaction_items.tax_items.destination_currency

enum<string>

Available options:

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

transaction_items.tax_items.external_id

string

transaction_items.tax_items.type

enum<string>

default:IMPORTED

Available options:

IMPORTED_ORIGINAL,

IMPORTED,

CALCULATED

Maximum string length: 50

transaction_items.tax_items.jurisdiction_type

enum<string>

Available options:

COUNTRY,

FEDERAL,

STATE,

COUNTY,

CITY,

SPECIAL,

OTHER,

HYBRID

transaction_items.tax_items.jurisdiction_name

string

description

string

Brief explanation or reason for issuing the credit note.

marketplace

boolean

default:false

Indicates whether this credit note is associated with a marketplace transaction.

tax_amount_imported

number

Pre-calculated total tax amount for the entire credit note, if provided by the external system.

tax_rate_imported

number

Pre-calculated overall tax rate for the credit note, if provided by the external system.

taxable_amount

number

Total portion of the credit note amount subject to taxation.

addresses

TransactionAddressBuilder · object[]

A list of TransactionAddressBuilder objects or None if no addresses are provided. This field represents the addresses associated with the transaction.

Show child attributes

addresses.type

enum<string>

required

Type of address. Allowed values: BILL_TO, SHIP_TO.

Available options:

BILL_TO,

SHIP_TO,

SHIP_FROM,

BILL_FROM

addresses.phone

string

Phone number associated with the address.

addresses.street_1

string

Primary street address.

addresses.street_2

string

Additional street address details, such as an apartment or suite number.

addresses.city

string

City where the customer resides.

addresses.county

string

County or district of the customer.

addresses.state

string

State or province of the customer.

addresses.postal_code

string

ZIP or Postal code of the customer.

addresses.country

enum<string>

Country code in ISO 3166-1 alpha-2 format

Available options:

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

addresses.full_address

string

Complete address string of the customer, which can be used as an alternative to individual fields.

addresses.enriched_fields

string

Optional additional enriched data for the address.

addresses.status

enum<string>

default:UNVERIFIED

Address verification status.** This field is ignored when updating addresses. The status of the address is updated automatically. **

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

addresses.organization_id

string

Response

Successful Response

organization_id

string

required

deprecated

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.

external_id

string

required

External identifier of the transaction.

date

string<date-time>

required

Transaction date and time

string

required

The unique transaction identifier.

addresses

TransactionAddressRead · object[]

required

List of addresses associated.

Show child attributes

addresses.type

enum<string>

required

Type of address. Allowed values: BILL_TO, SHIP_TO.

Available options:

BILL_TO,

SHIP_TO,

SHIP_FROM,

BILL_FROM

addresses.phone

string

Phone number associated with the address.

addresses.street_1

string

Primary street address.

addresses.street_2

string

Additional street address details, such as an apartment or suite number.

addresses.city

string

City where the customer resides.

addresses.county

string

County or district of the customer.

addresses.state

string

State or province of the customer.

addresses.postal_code

string

ZIP or Postal code of the customer.

addresses.country

enum<string>

Country code in ISO 3166-1 alpha-2 format

Available options:

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

addresses.full_address

string

Complete address string of the customer, which can be used as an alternative to individual fields.

addresses.status

enum<string>

default:UNVERIFIED

Address verification status.** This field is ignored when updating addresses. The status of the address is updated automatically. **

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

addresses.id

string

Unique identifier of the address being updated.

addresses.transaction_id

string

ID of the transaction associated with the address.

addresses.connection_id

string

ID of the connection associated with the address.

transaction_items

TransactionItemRead · object[]

required

List of items in the transaction.

Show child attributes

transaction_items.organization_id

string

required

deprecated

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.

transaction_items.date

string<date-time>

required

Date/time of item.

transaction_items.external_product_id

string

required

External product identifier.

transaction_items.id

string

required

The unique transaction item identifier.

transaction_items.tax_items

TaxItemRead · object[]

required

List of tax items associated with the transaction item.

Show child attributes

transaction_items.tax_items.rate

string

required

transaction_items.tax_items.amount

string

required

transaction_items.tax_items.name

string

required

Deprecated: use jurisdiction_type instead

Maximum string length: 250

transaction_items.tax_items.rule_id

string

default:0000

The rule ID of the tax item

transaction_items.tax_items.converted_amount

string

transaction_items.tax_items.currency

enum<string>

Available options:

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

transaction_items.tax_items.destination_currency

enum<string>

Available options:

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

transaction_items.tax_items.external_id

string

transaction_items.tax_items.type

enum<string>

default:IMPORTED

Available options:

IMPORTED_ORIGINAL,

IMPORTED,

CALCULATED

Maximum string length: 50

transaction_items.tax_items.jurisdiction_type

enum<string>

Available options:

COUNTRY,

FEDERAL,

STATE,

COUNTY,

CITY,

SPECIAL,

OTHER,

HYBRID

transaction_items.tax_items.jurisdiction_name

string

transaction_items.external_id

string

External item identifier.

transaction_items.description

string

Item description

transaction_items.product

string

Product name

transaction_items.product_id

string

Product identifier.

transaction_items.product_name

string

Product name (detailed)

transaction_items.product_description

string

Product description

transaction_items.quantity

string

default:1.0

Quantity of item.

transaction_items.amount

string

default:0.00

Item amount.

transaction_items.tax_amount_imported

string

default:0.00

Imported tax amount for the item.

transaction_items.tax_rate_imported

string

default:0.00

Imported tax rate.

transaction_items.tax_amount_calculated

string

default:0.00

Calculated tax amount for the item.

transaction_items.tax_rate_calculated

string

default:0.00

Calculated tax rate.

transaction_items.original_currency

enum<string>

Original currency code.

Available options:

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

transaction_items.destination_currency

enum<string>

Destination currency code.

Available options:

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

transaction_items.converted_amount

string

Converted item amount.

transaction_items.converted_taxable_amount

string

Converted taxable amount.

transaction_items.converted_tax_amount_imported

string

Converted imported tax amount.

transaction_items.converted_tax_amount_calculated

string

Converted calculated tax amount

transaction_items.converted_total_discount

string

Converted total discount amount.

transaction_items.converted_subtotal

string

Converted subtotal amount.

transaction_items.taxable_amount

string

default:0.00

Taxable amount for the item.

transaction_items.tax_exemption

enum<string>

Tax exemption status.

Available options:

PRODUCT,

TRANSACTION,

CUSTOMER,

REGION,

REVERSE_CHARGE,

ZERO_RATE_TAX,

HIGH_VALUE_PHYSICAL_GOODS,

EXPORT,

ZERO_VALUE_ITEM,

NO_RULE_FOUND,

IMPORTED

transaction_items.exempt

boolean

default:false

Indicates if the item is exempt.

transaction_items.total_discount

string

Total discount amount applied to this transaction item.

transaction_items.subtotal

string

Subtotal amount before any discount is applied.

type

enum<string>

required

The type of transaction (e.g., SALE, REFUND, PARTIAL_CREDIT_NOTE).

Available options:

SALE,

FULL_CREDIT_NOTE,

PARTIAL_CREDIT_NOTE,

TAX_REFUND,

ARCHIVE

requires_exemption

ExemptionRequired · object

Indicates if transaction requires tax exemption.

Show child attributes

requires_exemption.organization_id

string

required

deprecated

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.

requires_exemption.exemption_type

enum<string>

required

Available options:

customer,

wholesale,

transaction

requires_exemption.start_date

string<date-time>

required

requires_exemption.status

enum<string>

required

Available options:

ACTIVE,

INACTIVE,

EXPIRED,

DEACTIVATED,

ARCHIVED

requires_exemption.reseller

boolean

required

requires_exemption.jurisdiction

string

requires_exemption.customer_id

string

shop_date

string

Transaction date in the shop's local timezone

shop_date_tz

string

Timezone of the shop

description

string

Description of the transaction.

refund_status

enum<string>

Status of refund, if applicable

Available options:

FULLY_REFUNDED,

PARTIALLY_REFUNDED

total_amount

string

default:0.00

Total amount of the transaction.

customer_id

string

Unique identifier of the customer.

marketplace

boolean

default:false

Indicates if transaction is marketplace-based.

exempt

enum<string>

default:NOT_EXEMPT

Exemption status (e.g., NOT_EXEMPT)

Available options:

NOT_EXEMPT,

PARTIALLY_EXEMPT,

FULLY_EXEMPT

exemptions

Exemption · object[]

List of exemptions applied (if any).

Show child attributes

exemptions.exemption_type

enum<string>

required

The type of exemption (e.g., wholesale, resale)

Available options:

customer,

wholesale,

transaction

exemptions.start_date

string<date>

required

Start date for the exemption validity period (YYYY-MM-DD format)

exemptions.id

string

Unique identifier for the exemption

Maximum string length: 100

exemptions.created_at

string<date-time>

Timestamp when transaction was created in Kintsugi.

exemptions.updated_at

string

Timestamp when transaction was last updated.

exemptions.jurisdiction

string

The jurisdiction identifier for the exemption

exemptions.country_code

enum<string>

Country code in ISO 3166-1 alpha-2 format (e.g., 'US')

Available options:

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

exemptions.end_date

string

End date for the exemption validity period (YYYY-MM-DD format)

exemptions.customer_id

string

Unique identifier for the customer associated with the exemption

exemptions.transaction_id

string

Unique identifier for the transaction associated with the exemption, if applicable.

exemptions.reseller

boolean

default:false

Indicates whether the exemption is for a reseller

exemptions.FEIN

string

Federal Employer Identification Number associated with the exemption.

exemptions.sales_tax_id

string

Sales tax ID for the exemption

exemptions.status

enum<string>

The status of the exemption. Defaults to ACTIVE if not provided.

Available options:

ACTIVE,

INACTIVE,

EXPIRED,

DEACTIVATED,

ARCHIVED

exemptions.organization_id

string

Maximum string length: 100

Related transaction identifier.

secondary_external_id

string

Secondary External Identifier.

secondary_source

string

Secondary source information

external_friendly_id

string

Friendly identifier of the original item.

total_tax_amount_imported

string

default:0.00

Imported tax amount.

tax_rate_imported

string

default:0.00

Imported tax rate.

total_tax_amount_calculated

string

default:0.00

Calculated tax amount.

tax_rate_calculated

string

default:0.00

Calculated tax rate.

total_tax_liability_amount

string

default:0.00

Total tax liability amount.

tax_liability_source

enum<string>

Source of tax liability.

Available options:

CALCULATED,

COLLECTED

taxable_amount

string

default:0.00

Taxable amount.

currency

enum<string>

default:USD

Currency code (ISO 4217, e.g., USD)

Available options:

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

locked

boolean

default:false

Transaction lock status.

source

enum<string>

default:OTHER

Source platform (e.g., STRIPE)

Available options:

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

connection_id

string

Connection Identifier

filing_id

string

Filing identifier.

city

string

City of the transaction address.

county

string

County of the transaction address.

state

string

State of the transaction address.

country

enum<string>

Country code (ISO Alpha-2).

Available options:

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

postal_code

string

Postal code of the transaction.

tax_id

string

deprecated

Tax ID associated with the transaction. DEPRECATED: This field is only populated for QuickBooks integrations and will be removed in a future version.

status

enum<string>

default:COMMITTED

Transaction status (e.g., COMMITTED)

Available options:

PENDING,

COMMITTED,

CANCELLED,

FULLY_REFUNDED,

PARTIALLY_REFUNDED,

INVALID,

ARCHIVED

address_status

enum<string>

default:UNVERIFIED

Address verification status (e.g., VERIFIED).

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

processing_status

enum<string>

default:QUEUED

Status of processing (e.g., ADDRESS_DONE)

Available options:

NEW,

UPDATED,

QUEUED,

ADDRESS_DONE,

EXEMPT_DONE,

NEXUS_DONE,

PROCESSED,

FILING_STARTED,

FILING_DONE,

LOCKED,

PENDING,

ARCHIVED,

NEEDS_REFETCH

destination_currency

enum<string>

Destination currency code (ISO 4217, e.g., USD)

Available options:

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

converted_total_amount

string

Converted total amount.

converted_total_tax_amount_imported

string

Converted imported tax amount.

converted_total_tax_amount_calculated

string

Converted calculated tax amount.

conversion_rate

string

Currency conversion rate.

converted_taxable_amount

string

Converted taxable amount.

converted_total_discount

string

Converted total discount amount.

converted_subtotal

string

Converted subtotal amount.

converted_total_tax_liability_amount

string

Converted total tax liability amount.

customer

CustomerRead · object

Customer information associated with the transaction.

Show child attributes

customer.id

string

required

Unique identifier for the customer required.

customer.organization_id

string

required

Unique identifier for the organization associated with the customer. Required.

customer.phone

string

Customer's phone number

customer.street_1

string

Primary street address.

customer.street_2

string

Additional street address details, such as an apartment or suite number.

customer.city

string

City where the customer resides.

customer.county

string

County or district of the customer.

customer.state

string

State or province of the customer.

customer.postal_code

string

ZIP or Postal code of the customer.

customer.country

enum<string>

Country code in ISO 3166-1 alpha-2 format

Available options:

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

customer.full_address

string

Complete address string of the customer, which can be used as an alternative to individual fields.

customer.name

string

Name of the customer.

customer.external_id

string

External identifier associated with the customer.

customer.status

enum<string>

default:ACTIVE

Status of the customer.

Available options:

ACTIVE,

ARCHIVED

customer.email

string

Customer's email address

customer.source

enum<string>

Source of the customer's record.

Available options:

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

customer.connection_id

string

Identifier for the connection source, if applicable.

customer.address_status

enum<string>

default:UNVERIFIED

Status of address verification

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

customer.registration_number

string

Registration number of the customer.

customer.external_friendly_id

string

External friendly identifier associated with the customer. We need it for netsuite.

customer.customer_tax_registrations

CustomerTaxRegistrationRead · object[]

Customer tax registrations associated with the customer.

Show child attributes

customer.customer_tax_registrations.id

string

required

customer.customer_tax_registrations.customer_id

string

required

customer.customer_tax_registrations.country_code

enum<string>

required

Available options:

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

customer.customer_tax_registrations.tax_type

enum<string>

required

Enum for customer tax registration types.

Available options:

gst,

hst,

gst_hst,

qst,

pst,

rst,

vat,

unknown

customer.customer_tax_registrations.tax_id

string

required

customer.customer_tax_registrations.is_valid

boolean

required

total_discount

string

Total amount of all discounts applied to the transaction.

subtotal

string

Subtotal amount before any discounts are applied.

final_total_amount

string

Final total amount including tax liability.

converted_final_total_amount

string

Converted final total amount including tax liability.

​Creating Credit Notes

​Overview

​When to Create Credit Notes

​Prerequisites

​Workflow

​Step 1: Find Original Transaction

​Step 2: Create Credit Note

​Required Fields

​Example Request

​Step 3: Retrieve Credit Notes

​Authentication

​Try It Out

​Common Use Cases

​Full Refund

​Partial Refund

​Response Fields

​Next Steps

​Related Resources

Authorizations

Path Parameters

Body

Response

Creating Credit Notes

Overview

When to Create Credit Notes

Prerequisites

Workflow

Step 1: Find Original Transaction

Step 2: Create Credit Note

Required Fields

Example Request

Step 3: Retrieve Credit Notes

Authentication

Try It Out

Common Use Cases

Full Refund

Partial Refund

Response Fields

Next Steps

Related Resources