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.

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 have status "COMMITTED"
3. The Kintsugi transaction ID (not the external_id)

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

Try It Out

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

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