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.

In the Tenanted API a credit note is a transaction. You create one with POST /transactions, setting type to a credit-note type and naming the sale it reverses in originalTransactionId.

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:

1. The original transaction must exist in Kintsugi
2. The original transaction must be a sale whose status is PENDING, COMMITTED, or PARTIALLY_REFUNDED
3. The Kintsugi transaction ID (not the externalId)
4. An externalId on each original line you plan to credit, since every credited line must reference one

Workflow

1. Find Original Transaction - Retrieve the original transaction to get its Kintsugi ID
2. Create Credit Note - Create a credit note linked to the original transaction
3. 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 /transactions?search={externalId} - The search parameter covers externalId, along with the transaction id, externalFriendlyId, description and customer name
• GET /transactions/{transaction_id} - Read back a transaction you already hold the ID for, including its lines

Step 2: Create Credit Note

Create a credit note using the API Lab below with POST /transactions, a credit-note type and originalTransactionId.

The credit note inherits the original transaction's customer, addresses and source, so send only the lines to credit in items. Each line carries the externalId of the original line it reverses, the externalProductId of the product on that line, and a taxableAmount.

Example Request

{
  "externalId": "cn-1",
  "date": "2026-07-21T15:30:00Z",
  "type": "FULL_CREDIT_NOTE",
  "originalTransactionId": "tran_12345",
  "currency": "USD",
  "totalAmount": "100.00",
  "items": [
    {
      "externalId": "item-1",
      "externalProductId": "SKU-ABC",
      "date": "2026-07-21T15:30:00Z",
      "quantity": "2",
      "amount": "100.00",
      "taxableAmount": "100.00"
    }
  ]
}

Send amounts as positive values; the stored credit note reads them back as negative. The API answers 202 Accepted. The stored type is derived from the amount credited, so a FULL_CREDIT_NOTE that credits less than the sale reads back as PARTIAL_CREDIT_NOTE, and the reverse.

Step 3: Retrieve Credit Notes

Retrieve the credit notes for a sale with GET /transactions/{transaction_id}/related, passing the original transaction's ID. It lists the credit notes that reverse a sale, or, from a credit note, the original sale it reverses.

Credit notes also appear in transaction queries. Use GET /transactions with:

• type: Filter by CREDIT_NOTE, which groups every credit-note type
• search: Search by credit note externalId

Authentication

These endpoints take one credential header:

• Api-Key: Your API key

Try It Out

Required Fields

• externalId: Your unique credit note identifier
• date: When the credit note was issued
• currency: ISO 4217 currency of every amount sent (for example, USD)
• type: FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE
• originalTransactionId: The Kintsugi ID of the committed sale being reversed
• items: At least one line to credit, each with:
  • externalId: The externalId of the original line being reversed
  • externalProductId: The product on that original line
  • date: Date and time of the line
  • taxableAmount: The taxable portion being reversed on that line

The schema itself requires only externalId, date and currency. The other fields are required when type is a credit-note type, and a request without them is rejected with 400.

Common Use Cases

Full Refund

Create a credit note for a full refund:

{
  "externalId": "cn-1",
  "date": "2026-07-21T15:30:00Z",
  "type": "FULL_CREDIT_NOTE",
  "originalTransactionId": "tran_12345",
  "currency": "USD",
  "totalAmount": "100.00",
  "items": [
    {
      "externalId": "item-1",
      "externalProductId": "SKU-ABC",
      "date": "2026-07-21T15:30:00Z",
      "quantity": "2",
      "amount": "100.00",
      "taxableAmount": "100.00"
    }
  ]
}

Partial Refund

Create a credit note for a partial refund:

{
  "externalId": "cn-2",
  "date": "2026-07-21T15:30:00Z",
  "type": "PARTIAL_CREDIT_NOTE",
  "originalTransactionId": "tran_12345",
  "currency": "USD",
  "totalAmount": "40.00",
  "items": [
    {
      "externalId": "item-1",
      "externalProductId": "SKU-ABC",
      "date": "2026-07-21T15:30:00Z",
      "quantity": "1",
      "amount": "40.00",
      "taxableAmount": "40.00"
    }
  ]
}

A credit note cannot credit more than is still creditable on the original transaction, or on any original line.

Response Fields

Next Steps

• List transactions - List and search credit notes
• List related transactions - List the credit notes that reverse a sale
• Update a credit note - Modify credit note details
• Handling Refund Transactions - Learn more about credit notes

Related Resources

• Create a Transaction API Reference
• Getting Started
• Support