Create Transaction

Create a transaction.

POST /v1/transactions

Create Transaction

cURL

curl --request POST \
  --url https://api.trykintsugi.com/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "organization_id": "orgn_YourOrgIdHere",
  "external_id": "YourUniqueOrder123",
  "date": "2024-01-15T14:30:00Z",
  "type": "SALE",
  "customer": {
    "organization_id": "orgn_YourOrgIdHere",
    "external_id": "Cust456",
    "name": "John Doe"
  },
  "addresses": [
    {
      "type": "SHIP_TO",
      "country": "US",
      "state": "CA",
      "city": "San Francisco",
      "postal_code": "94107",
      "street_1": "123 Main St"
    }
  ],
  "transaction_items": [
    {
      "organization_id": "orgn_YourOrgIdHere",
      "date": "2024-01-15T14:30:00Z",
      "external_product_id": "SKU-ABC",
      "product": "Example Widget",
      "quantity": 2,
      "amount": 50
    }
  ]
}
'

202

Example

[ { "organization_id": "orgn_YOURORGID", "external_id": "tran_YOURTRANSACTIONID", "date": "2024-01-15T14:30:00", "status": "COMMITTED", "description": "Order with one taxable book and one exempt service", "processing_status": "QUEUED", "total_amount": "200.00", "customer_id": "cust_afXm2qPEycF83", "marketplace": false, "exempt": "FULLY_EXEMPT", "exemptions": [ { "updated_at": "2025-05-22T14:48:46.056060", "start_date": "2025-01-23", "transaction_id": "tran_nc5Q4hLi97NRD", "reseller": true, "status": "ACTIVE", "created_at": "2025-05-22T14:48:46.193109", "exemption_type": "transaction", "customer_id": "cust_afXm2qPEycF83", "id": "exmp_xfLpDHxxX4Cxv", "organization_id": "orgn_UT7zEcgwt4Fhk" } ], "total_tax_amount_imported": "6.00", "tax_rate_imported": "0.030000000", "total_tax_amount_calculated": "0.00", "tax_rate_calculated": "0E-9", "total_tax_liability_amount": "6.00", "tax_liability_source": "COLLECTED", "taxable_amount": "200.00", "currency": "USD", "locked": false, "source": "API", "address_status": "UNVERIFIED", "id": "tran_g9WJFTdFjLzDv", "addresses": [ { "street_1": "123 Main St", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US", "type": "SHIP_TO", "status": "UNVERIFIED", "id": "addr_tWqfSwDZK7aSt", "transaction_id": "tran_g9WJFTdFjLzDv" } ], "transaction_items": [ { "external_id": "LI_BOOK_TAXABLE_001", "organization_id": "orgn_YOURORGID", "date": "2025-01-24T11:00:00", "external_product_id": "PROD_BOOK_SCIFI_HC", "product": "Sci-Fi Hardcover Novel", "product_id": "prod_AKczKRGnAe3d3", "quantity": "1", "amount": "100.00", "tax_amount_imported": "6.00", "tax_rate_imported": "0.060000000", "tax_amount_calculated": "0.00", "tax_rate_calculated": "0E-9", "taxable_amount": "100.00", "exempt": false, "id": "txim_c63o27oiEhLuA", "tax_items": [ { "rule_id": "0000", "rate": "0.060000000", "amount": "6.00", "name": "PA State Sales Tax", "type": "IMPORTED", "jurisdiction_type": "STATE", "jurisdiction_name": "PA" } ], "total_discount": "0.00", "subtotal": "100.00" }, { "external_id": "LI_SERVICE_EXEMPT_002", "organization_id": "orgn_YOURORGID", "date": "2025-01-24T11:00:00", "external_product_id": "PROD_DIGITAL_SERVICE_EX", "product": "Digital Marketing Service (Non-Taxable in PA)", "product_id": "prod_zz2RshS8uweRe", "quantity": "1", "amount": "100.00", "tax_amount_imported": "0.00", "tax_rate_imported": "0E-9", "tax_amount_calculated": "0.00", "tax_rate_calculated": "0E-9", "taxable_amount": "100.00", "tax_exemption": "PRODUCT", "exempt": false, "id": "txim_eqwAKmiDpgf2m", "tax_items": [], "total_discount": "0.00", "subtotal": "100.00" } ], "customer": { "name": "John Doe", "external_id": "Cust456", "status": "ACTIVE", "email": "[e-mail]", "address_status": "UNVERIFIED", "id": "cust_afXm2qPEycF83", "organization_id": "orgn_YOURORGID" }, "type": "SALE", "total_discount": "0.00", "subtotal": "200.00" } ]

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.

Minimum string length: 1

date · string<date-time> · required

Transaction date and time

addresses · TransactionAddressPublic · object[] · required

Show child attributes

transaction_items · TransactionItemBuilder · object[] · required

Show child attributes

customer · Customer · object · required

Show child attributes

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

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, ZERO_RATE_NOT_EXEMPT

exemptions · Exemption · object[]

List of exemptions applied (if any).

Show child attributes

related_to · string

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, MICROSOFT_DYNAMICS_365, KICKSTARTER, INTERNAL_ERP

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

202

application/json

Successfully created transaction