# Creating Credit Notes

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

Source: https://docs.trykintsugi.com/docs/recipes/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 API Lab below with POST /v1/transactions/{original_transaction_id}/credit_notes.

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

API Lab Simulated

Run all Reset Share Copy cURL Postman

Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.

1 Create the original transaction

POST /v1/transactions

{

"organization_id": "orgn_YourOrgIdHere",

"external_id": "YourUniqueOrder123",

"date": "2024-01-15T14:30:00Z",

"type": "SALE",

"currency": "USD",

"marketplace": true,

"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

}

],

"source": "API"

}

{
"organization_id": "orgn_YourOrgIdHere",
"external_id": "YourUniqueOrder123",
"date": "2024-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"marketplace": true,
"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
}
],
"source": "API"
}

Run

2 Issue a credit note

POST /v1/transactions/{original_transaction_id}/credit_notes

{

"external_id": "CN-12345",

"date": "2024-10-27T14:30:00Z",

"status": "PENDING",

## Try It Out

"description": "Refund for damaged product",

"total_amount": 50,

"external_customer_id": "CUST-456",

"currency": "USD",

"transaction_items": [

{

"external_id": "ITEM-1",

"date": "2024-10-27T14:30:00Z",

"external_product_id": "PROD-ABC",

"quantity": 1,

"amount": 50

}

]

}

{
"external_id": "CN-12345",
"date": "2024-10-27T14:30:00Z",
"status": "PENDING",
"description": "Refund for damaged product",
"total_amount": 50,
"external_customer_id": "CUST-456",
"currency": "USD",
"transaction_items": [
{
"external_id": "ITEM-1",
"date": "2024-10-27T14:30:00Z",
"external_product_id": "PROD-ABC",
"quantity": 1,
"amount": 50
}
]
}

Run Run the previous step to fill the path.

## Required Fields

original_transaction_id (path): The ID of the original transaction being credited

external_id: Your unique credit note identifier

date: Credit note date in ISO 8601 format

status: Credit note status (for example, PENDING)

total_amount: The refund amount

currency: Three-letter currency code (for example, USD)

transaction_items: The line items being credited, each with an amount

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

id: Kintsugi's unique credit note identifier

external_id: Your credit note identifier

related_to: The original transaction this credit note applies to

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

## Related Resources

Create Credit Note API Reference

Getting Started

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt