POST

transactions

{original_transaction_id}

credit_notes

Create Credit Note By Transaction Id

curl --request POST \
  --url https://api.trykintsugi.com/v1/transactions/{original_transaction_id}/credit_notes \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "external_id": "CN-12345",
  "date": "2024-10-27T14:30:00Z",
  "status": "PENDING",
  "total_amount": 50,
  "currency": "USD",
  "transaction_items": [
    {
      "external_id": "ITEM-1",
      "date": "2024-10-27T14:30:00Z",
      "external_product_id": "PROD-ABC",
      "quantity": 1,
      "amount": 50
    }
  ]
}
'

{
  "organization_id": "<string>",
  "external_id": "<string>",
  "date": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "addresses": [
    {
      "phone": "<string>",
      "street_1": "<string>",
      "street_2": "<string>",
      "city": "<string>",
      "county": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "full_address": "<string>",
      "status": "UNVERIFIED",
      "id": "<string>",
      "transaction_id": "<string>",
      "connection_id": "<string>"
    }
  ],
  "transaction_items": [
    {
      "organization_id": "<string>",
      "date": "2023-11-07T05:31:56Z",
      "external_product_id": "<string>",
      "id": "<string>",
      "tax_items": [
        {
          "rate": "<string>",
          "amount": "<string>",
          "name": "<string>",
          "rule_id": "0000",
          "converted_amount": "<string>",
          "external_id": "<string>",
          "type": "IMPORTED",
          "jurisdiction_name": "<string>"
        }
      ],
      "external_id": "<string>",
      "description": "<string>",
      "product": "<string>",
      "product_id": "<string>",
      "product_name": "<string>",
      "product_description": "<string>",
      "quantity": "1.0",
      "amount": "0.00",
      "tax_amount_imported": "0.00",
      "tax_rate_imported": "0.00",
      "tax_amount_calculated": "0.00",
      "tax_rate_calculated": "0.00",
      "converted_amount": "<string>",
      "converted_taxable_amount": "<string>",
      "converted_tax_amount_imported": "<string>",
      "converted_tax_amount_calculated": "<string>",
      "converted_total_discount": "<string>",
      "converted_subtotal": "<string>",
      "taxable_amount": "0.00",
      "exempt": false,
      "total_discount": "<string>",
      "subtotal": "<string>"
    }
  ],
  "requires_exemption": {
    "organization_id": "<string>",
    "start_date": "2023-11-07T05:31:56Z",
    "reseller": true,
    "jurisdiction": "<string>",
    "customer_id": "<string>"
  },
  "shop_date": "<string>",
  "shop_date_tz": "<string>",
  "description": "<string>",
  "total_amount": "0.00",
  "customer_id": "<string>",
  "marketplace": false,
  "exempt": "NOT_EXEMPT",
  "exemptions": [
    {
      "start_date": "2023-12-25",
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "<string>",
      "jurisdiction": "<string>",
      "end_date": "<string>",
      "customer_id": "<string>",
      "transaction_id": "<string>",
      "reseller": false,
      "FEIN": "<string>",
      "sales_tax_id": "<string>",
      "organization_id": "<string>"
    }
  ],
  "related_to": "<string>",
  "secondary_external_id": "<string>",
  "secondary_source": "<string>",
  "external_friendly_id": "<string>",
  "total_tax_amount_imported": "0.00",
  "tax_rate_imported": "0.00",
  "total_tax_amount_calculated": "0.00",
  "tax_rate_calculated": "0.00",
  "total_tax_liability_amount": "0.00",
  "taxable_amount": "0.00",
  "currency": "USD",
  "locked": false,
  "source": "OTHER",
  "connection_id": "<string>",
  "filing_id": "<string>",
  "city": "<string>",
  "county": "<string>",
  "state": "<string>",
  "postal_code": "<string>",
  "tax_id": "<string>",
  "status": "COMMITTED",
  "address_status": "UNVERIFIED",
  "processing_status": "QUEUED",
  "converted_total_amount": "<string>",
  "converted_total_tax_amount_imported": "<string>",
  "converted_total_tax_amount_calculated": "<string>",
  "conversion_rate": "<string>",
  "converted_taxable_amount": "<string>",
  "converted_total_discount": "<string>",
  "converted_subtotal": "<string>",
  "converted_total_tax_liability_amount": "<string>",
  "customer": {
    "id": "<string>",
    "organization_id": "<string>",
    "phone": "<string>",
    "street_1": "<string>",
    "street_2": "<string>",
    "city": "<string>",
    "county": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "full_address": "<string>",
    "name": "<string>",
    "external_id": "<string>",
    "status": "ACTIVE",
    "email": "<string>",
    "connection_id": "<string>",
    "address_status": "UNVERIFIED",
    "registration_number": "<string>",
    "external_friendly_id": "<string>",
    "customer_tax_registrations": [
      {
        "id": "<string>",
        "customer_id": "<string>",
        "tax_id": "<string>",
        "is_valid": true
      }
    ]
  },
  "total_discount": "<string>",
  "subtotal": "<string>",
  "final_total_amount": "<string>",
  "converted_final_total_amount": "<string>"
}

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

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

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.

Minimum string length: 1

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

transaction_items

TransactionItemRead · object[]

required

List of items in the transaction.

Show child attributes

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

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.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)

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

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)

tax_rate_imported

string

default:0.00

Imported tax rate.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)

total_tax_amount_calculated

string

default:0.00

Calculated tax amount.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)

tax_rate_calculated

string

default:0.00

Calculated tax rate.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,3}|(?=[\d.]{1,13}0*$)\d{0,3}\.\d{0,9}0*$)

total_tax_liability_amount

string

default:0.00

Total tax liability amount.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)

tax_liability_source

enum<string>

Source of tax liability.

Available options:

CALCULATED,

COLLECTED

taxable_amount

string

default:0.00

Taxable amount.

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)

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

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,

EXCLUDED_IN_CALCULATION

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

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.

Managing NexusInteractive playground for creating physical nexus, registrations, and retrieving nexus information

⌘I

Create Credit Note By Transaction Id

curl --request POST \
  --url https://api.trykintsugi.com/v1/transactions/{original_transaction_id}/credit_notes \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "external_id": "CN-12345",
  "date": "2024-10-27T14:30:00Z",
  "status": "PENDING",
  "total_amount": 50,
  "currency": "USD",
  "transaction_items": [
    {
      "external_id": "ITEM-1",
      "date": "2024-10-27T14:30:00Z",
      "external_product_id": "PROD-ABC",
      "quantity": 1,
      "amount": 50
    }
  ]
}
'

{
  "organization_id": "<string>",
  "external_id": "<string>",
  "date": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "addresses": [
    {
      "phone": "<string>",
      "street_1": "<string>",
      "street_2": "<string>",
      "city": "<string>",
      "county": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "full_address": "<string>",
      "status": "UNVERIFIED",
      "id": "<string>",
      "transaction_id": "<string>",
      "connection_id": "<string>"
    }
  ],
  "transaction_items": [
    {
      "organization_id": "<string>",
      "date": "2023-11-07T05:31:56Z",
      "external_product_id": "<string>",
      "id": "<string>",
      "tax_items": [
        {
          "rate": "<string>",
          "amount": "<string>",
          "name": "<string>",
          "rule_id": "0000",
          "converted_amount": "<string>",
          "external_id": "<string>",
          "type": "IMPORTED",
          "jurisdiction_name": "<string>"
        }
      ],
      "external_id": "<string>",
      "description": "<string>",
      "product": "<string>",
      "product_id": "<string>",
      "product_name": "<string>",
      "product_description": "<string>",
      "quantity": "1.0",
      "amount": "0.00",
      "tax_amount_imported": "0.00",
      "tax_rate_imported": "0.00",
      "tax_amount_calculated": "0.00",
      "tax_rate_calculated": "0.00",
      "converted_amount": "<string>",
      "converted_taxable_amount": "<string>",
      "converted_tax_amount_imported": "<string>",
      "converted_tax_amount_calculated": "<string>",
      "converted_total_discount": "<string>",
      "converted_subtotal": "<string>",
      "taxable_amount": "0.00",
      "exempt": false,
      "total_discount": "<string>",
      "subtotal": "<string>"
    }
  ],
  "requires_exemption": {
    "organization_id": "<string>",
    "start_date": "2023-11-07T05:31:56Z",
    "reseller": true,
    "jurisdiction": "<string>",
    "customer_id": "<string>"
  },
  "shop_date": "<string>",
  "shop_date_tz": "<string>",
  "description": "<string>",
  "total_amount": "0.00",
  "customer_id": "<string>",
  "marketplace": false,
  "exempt": "NOT_EXEMPT",
  "exemptions": [
    {
      "start_date": "2023-12-25",
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "<string>",
      "jurisdiction": "<string>",
      "end_date": "<string>",
      "customer_id": "<string>",
      "transaction_id": "<string>",
      "reseller": false,
      "FEIN": "<string>",
      "sales_tax_id": "<string>",
      "organization_id": "<string>"
    }
  ],
  "related_to": "<string>",
  "secondary_external_id": "<string>",
  "secondary_source": "<string>",
  "external_friendly_id": "<string>",
  "total_tax_amount_imported": "0.00",
  "tax_rate_imported": "0.00",
  "total_tax_amount_calculated": "0.00",
  "tax_rate_calculated": "0.00",
  "total_tax_liability_amount": "0.00",
  "taxable_amount": "0.00",
  "currency": "USD",
  "locked": false,
  "source": "OTHER",
  "connection_id": "<string>",
  "filing_id": "<string>",
  "city": "<string>",
  "county": "<string>",
  "state": "<string>",
  "postal_code": "<string>",
  "tax_id": "<string>",
  "status": "COMMITTED",
  "address_status": "UNVERIFIED",
  "processing_status": "QUEUED",
  "converted_total_amount": "<string>",
  "converted_total_tax_amount_imported": "<string>",
  "converted_total_tax_amount_calculated": "<string>",
  "conversion_rate": "<string>",
  "converted_taxable_amount": "<string>",
  "converted_total_discount": "<string>",
  "converted_subtotal": "<string>",
  "converted_total_tax_liability_amount": "<string>",
  "customer": {
    "id": "<string>",
    "organization_id": "<string>",
    "phone": "<string>",
    "street_1": "<string>",
    "street_2": "<string>",
    "city": "<string>",
    "county": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "full_address": "<string>",
    "name": "<string>",
    "external_id": "<string>",
    "status": "ACTIVE",
    "email": "<string>",
    "connection_id": "<string>",
    "address_status": "UNVERIFIED",
    "registration_number": "<string>",
    "external_friendly_id": "<string>",
    "customer_tax_registrations": [
      {
        "id": "<string>",
        "customer_id": "<string>",
        "tax_id": "<string>",
        "is_valid": true
      }
    ]
  },
  "total_discount": "<string>",
  "subtotal": "<string>",
  "final_total_amount": "<string>",
  "converted_final_total_amount": "<string>"
}

​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