Creating Transactions

Overview

Transactions represent completed sales in Kintsugi. Each transaction records a sale with customer information, line items, addresses, and tax details. Transactions are used for compliance tracking, nexus determination, and tax filing preparation.

Only create transactions for completed sales with confirmed payment. Do not sync pending orders or estimates.

When to Create Transactions

After payment confirmation: When a sale is completed and payment is received
Order fulfillment: When an order is shipped or delivered
Invoice creation: When generating invoices for completed sales
Batch sync: Daily or periodic syncing of completed orders

Workflow

Create a Transaction - Record a completed sale
Retrieve Transactions - Search and retrieve transaction records

Step 1: Create a Transaction

Create a transaction using the interactive playground below with POST /v1/transactions.

Required Fields

external_id: Your internal transaction/order identifier (must be unique)
date: Transaction date and time (UTC)
currency: Currency code (e.g., USD, EUR)
total_amount: Total transaction amount
source: Source of the transaction (e.g., “API”, “SHOPIFY”)
status: Transaction status (use “COMMITTED” for completed sales)
type: Transaction type (typically “SALE”)
transaction_items: Array of line items
addresses: Array of addresses (at minimum: SHIP_TO or BILL_TO)

Example Request

{
  "external_id": "ORDER-12345",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 150.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Example Product",
      "quantity": "1.0",
      "amount": 100.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Step 2: Retrieve Transactions

After creating transactions, retrieve them using GET /v1/transactions. You can:

Filter by external_id using the search_query parameter
Filter by date range using date__gte and date__lte
Filter by status, state, country, and more
Paginate through results

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 transaction. The playground will automatically include the required authentication headers.

The playground prefills example values from the API schema. Modify the request body to test different transaction configurations.

Common Use Cases

Basic Transaction

Create a simple transaction with minimal required fields:

{
  "external_id": "ORDER-001",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 100.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Widget",
      "quantity": "1.0",
      "amount": 100.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Transaction with Customer

Include customer information:

{
  "external_id": "ORDER-002",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 200.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "customer": {
    "external_id": "CUST-001",
    "name": "John Doe",
    "email": "[email protected]",
    "street_1": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US"
  },
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Product A",
      "quantity": "2.0",
      "amount": 200.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Response Fields

The API returns detailed transaction information:

id: Kintsugi’s unique transaction identifier
external_id: Your transaction identifier
date: Transaction date
total_amount: Total transaction amount
total_tax_amount_calculated: Calculated tax amount
status: Transaction status
addresses: Array of addresses
transaction_items: Array of line items
customer: Customer information (if provided)

Next Steps

Get Transactions - List and search transactions
Get Transaction By ID - Retrieve specific transaction
Update Transaction - Modify transaction details
Syncing Transaction Records - Learn more about transaction management

Authorizations

X-API-KEY

string

header

required

x-organization-id

string

header

required

Body

application/json

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

addresses

TransactionAddressPublic · object[]

required

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.

transaction_items

TransactionItemBuilder · object[]

required

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.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

number

default:1.0

Quantity of item.

transaction_items.amount

number

default:0.00

Item amount.

transaction_items.tax_amount_imported

number

default:0.00

Imported tax amount for the item.

transaction_items.tax_rate_imported

number

default:0.00

Imported tax rate.

transaction_items.tax_amount_calculated

number

default:0.00

Calculated tax amount for the item.

transaction_items.tax_rate_calculated

number

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

number

Converted item amount.

transaction_items.converted_taxable_amount

number

Converted taxable amount.

transaction_items.converted_tax_amount_imported

number

Converted imported tax amount.

transaction_items.converted_tax_amount_calculated

number

Converted calculated tax amount

transaction_items.converted_total_discount

number

Converted total discount amount.

transaction_items.converted_subtotal

number

Converted subtotal amount.

transaction_items.taxable_amount

number

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.tax_items

TaxItemBuilder · object[]

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

transaction_items.discount_builder

DiscountBuilder · object

Show child attributes

transaction_items.discount_builder.applied_to

enum<string>

required

Available options:

TRANSACTION,

TRANSACTION_ITEM

transaction_items.discount_builder.external_id

string

transaction_items.discount_builder.discount_amount

number

default:0.00

customer

Customer · object

required

Show child attributes

customer.organization_id

string

required

Maximum string length: 100

customer.phone

string

Phone number associated with the address.

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

A unique identifier for the customer.

customer.status

enum<string>

default:ACTIVE

Status of the customer (e.g., ACTIVE, INACTIVE).

Available options:

ACTIVE,

ARCHIVED

customer.email

string

Email address of the customer.

customer.address_status

enum<string>

default:UNVERIFIED

Address status of the customer. Defaults to UNVERIFIED.

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

customer.source

enum<string>

Source of the customer information (e.g., BIGCOMMERCE, STRIPE, etc.).

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.registration_number

string

customer.connection_id

string

Unique identifier of the connection related to the customer.

customer.enriched_fields

string

Additional enriched fields for the customer, if available.

customer.is_test_data

boolean

default:false

type

enum<string>

required

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

number

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

number

default:0.00

Imported tax amount.

tax_rate_imported

number

default:0.00

Imported tax rate.

total_tax_amount_calculated

number

default:0.00

Calculated tax amount.

tax_rate_calculated

number

default:0.00

Calculated tax rate.

total_tax_liability_amount

number

default:0.00

Total tax liability amount.

tax_liability_source

enum<string>

Source of tax liability.

Available options:

CALCULATED,

COLLECTED

taxable_amount

number

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

Response

Successfully created transaction

​Creating Transactions

​Overview

​When to Create Transactions

​Workflow

​Step 1: Create a Transaction

​Required Fields

​Example Request

​Step 2: Retrieve Transactions

​Authentication

​Try It Out

​Common Use Cases

​Basic Transaction

​Transaction with Customer

​Response Fields

​Next Steps

​Related Resources

Authorizations

Body

Response

Creating Transactions

Overview

When to Create Transactions

Workflow

Step 1: Create a Transaction

Required Fields

Example Request

Step 2: Retrieve Transactions

Authentication

Try It Out

Common Use Cases

Basic Transaction

Transaction with Customer

Response Fields

Next Steps

Related Resources