---
title: "Issue a credit note against an invoice"
description: "Refund or balance."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/invoices/issue-a-credit-note-against-an-invoice"
---
# Issue a credit note against an invoice

> Refund or balance.

<api-operation method="POST" path="/v1/businesses/{biz}/credit_notes">
<template v-slot:docs="">

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
</tbody>
</table>

## Headers

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Idempotency-Key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Safely retry writes — repeats return the original response. If a write FAILED after it had already taken effect, that failure is what repeats: the key is spent, and a new attempt needs a new key.
    </td>
  </tr>
</tbody>
</table>

## Body

The request body is **required**.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        invoice
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The id of the invoice the credit note is for (inv_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kind
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      adjustment reduces what an UNPAID invoice still owes; refundable credits a PAID invoice and is refundable in cash or drawable against future invoices. One of <code>
        adjustment
      </code>
      
      , <code>
        refundable
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reason_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Reason code, e.g. write_off, order_cancellation, product_unsatisfactory.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reason
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Why the credit note is issued.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_notes
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A note to the customer, stored on the credit note.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The lines to credit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items.description
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      What the line is for.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items.amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The amount in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items.invoice_line_item
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The invoice line this item credits. When every item names a line, amount_minor is the amount credited against that line, tax included, and the note reverses tax at the tax rate of that line. When one or more items name no line, the note reverses tax at the average tax rate of the invoice. The items that name one line cannot together be more than that line's <code>
        creditable_minor
      </code>
      
       on the invoice; if they are, the request fails with 400.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items.period_start
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The window this item credits. Omit → the credited line's period.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items.period_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The end of the period the line covers (ISO-8601 UTC).
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The credit note's id (cn_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Human-readable sequential number ("CN-42"); null on rows predating it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The invoice this note credits (inv_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice_number
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      That invoice's human-readable number ("INV-42"); null on rows predating it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kind
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      adjustment reduces an unpaid invoice; refundable credits the refundable bucket and can be refunded or allocated. One of <code>
        adjustment
      </code>
      
      , <code>
        refundable
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        refunded
      </code>
      
       means nothing is left available: by a refund, by allocation to invoices, or both. <code>
        settled_by
      </code>
      
       says which. One of <code>
        adjusted
      </code>
      
      , <code>
        refund_due
      </code>
      
      , <code>
        refunded
      </code>
      
      , <code>
        voided
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settled_by
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Set on a <code>
        refunded
      </code>
      
       note: <code>
        refund
      </code>
      
       (cash went back), <code>
        allocation
      </code>
      
       (applied to invoices; <code>
        refunded_minor
      </code>
      
       is 0) or <code>
        mixed
      </code>
      
      . Null on every other status. One of <code>
        refund
      </code>
      
      , <code>
        allocation
      </code>
      
      , <code>
        mixed
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reason_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The credit note's reason code. One of <code>
        write_off
      </code>
      
      , <code>
        subscription_change
      </code>
      
      , <code>
        subscription_cancellation
      </code>
      
      , <code>
        chargeback
      </code>
      
      , <code>
        other
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subtotal_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The GROSS reversal this note documents, PRE-TAX and before any slice was routed back to a credit bucket. Reproduce the note as subtotal_minor − Σ discounts<span>
        
      </span>
      
      .amount_minor + tax = total_minor. Notes issued before this was recorded report their total_minor here, with no discounts and no tax.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The CASHABLE claim — what is refundable or allocatable, NOT the gross. 0 is legitimate: a reversal funded entirely from promotional credit returns all of it to that bucket.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        allocated_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Already applied to invoices.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refunded_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Already drawn as a refund.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        available_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      total_minor − allocated_minor − refunded_minor.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payout_unconfirmed_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      A payout refund the gateway could not confirm (not found). Counted as paid out until a person resolves it with <code>
        POST …/credit_notes/{cn}/resolve_payout
      </code>
      
      , or the gateway answers later (a success settles it as paid, a failure returns it as credit). 0 = nothing to resolve.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payout_duplicated_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      A refund that a person returned as credit and that the gateway later confirmed paid out: the customer has this amount as cash and as credit. We do not take the credit back on our own. A later bounce of that payout lowers it. 0 = none.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payout_out_of_order_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      A refund the gateway reported failed (we returned it as credit) and then reported paid: its answers arrived out of order. Booked as paid; the credit stays. Check the gateway. 0 = none.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The credit note's currency (ISO-4217 code).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exchange_rate
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      INHERITED from the invoice this note credits, not resolved fresh — so the note and its invoice convert at the same rate and net to zero in a converted book. Same string/direction rules as <code>
        Invoice.exchange_rate
      </code>
      
      ; null when the credited invoice carried no rate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exchange_rate_base
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The exchange rate to the business's default currency at issue.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reason
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Why the credit note was issued.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_notes
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      A note shown to the customer on the credit note.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        voided_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the credit note was voided (ISO-8601 UTC), or null.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        channel
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Provenance at creation; null on rows predating the column. One of <code>
        api
      </code>
      
      , <code>
        dashboard
      </code>
      
      , <code>
        system
      </code>
      
      , <code>
        import
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        imported
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Archival row imported from an external system (no ledger postings).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Key-value pairs you attach to the credit note.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        created_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the credit note was created (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The payer (cus_…). Absent on the create receipt.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_email
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's email.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The CASHABLE lines, so they sum to total_minor rather than to subtotal_minor — the gap is exactly <code>
        discounts[]
      </code>
      
      . Absent on the create receipt.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discounts
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      What was taken off subtotal_minor and which bucket it went back to. Amounts are positive magnitudes. Present on the single credit-note read only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        taxes
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The <code>
        + tax
      </code>
      
       term of that identity, split across the components the CREDITED INVOICE booked and named the way the invoice names them ("IGST (18.00%)"). A credit note stores neither the amount nor the names: the amount is the identity rearranged, the names come from the invoice's tax snapshot, in the proportion it booked them. Σ amount_minor === total_minor − subtotal_minor + Σ discounts<span>
        
      </span>
      
      .amount_minor. Falls back to a single unnamed "Tax" row when the credited invoice recorded no per-line tax (rows predating it, or an untaxed business). Empty when the note carries no tax. Present on the single credit-note read only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gateway_refundable_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Cash on this note's invoice still reversible through a gateway. 0 means a gateway refund is impossible. Present on the single credit-note read only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        allocations
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Where this note's credit was applied. Present on the single credit-note read only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refunds
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Refund transactions drawn against this note. Present on the single credit-note read only.
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        201
      </code>
    </td>
    
    <td>
      Created
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Over-credit / not refundable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        409
      </code>
    </td>
    
    <td>
      Idempotency-Key conflict — the key is already in flight, or was reused with a different request payload.
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl -X POST "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/credit_notes" \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "inv_XXXXXXXXXXXX01",
    "kind": "adjustment",
    "reason_code": "write_off",
    "items": [
      {
        "description": "Everything a growing team needs.",
        "amount_minor": 2900
      }
    ]
  }'
```

</template>

<template v-slot:response="">
<code-group>

```json [201 Created]
{
  "object": "credit_note",
  "id": "cn_XXXXXXXXXXXX01",
  "number": "INV-1001",
  "invoice": "inv_XXXXXXXXXXXX01",
  "invoice_number": "INV-1001",
  "kind": "adjustment",
  "status": "adjusted",
  "settled_by": "refund",
  "reason_code": null,
  "subtotal_minor": 2900,
  "total_minor": 2900,
  "allocated_minor": 2900,
  "refunded_minor": 0,
  "available_minor": 2900,
  "payout_unconfirmed_minor": 2900,
  "payout_duplicated_minor": 2900,
  "payout_out_of_order_minor": 2900,
  "currency": "USD",
  "exchange_rate": "0.920000",
  "exchange_rate_base": "USD",
  "reason": "Requested by the customer.",
  "customer_notes": "Thank you for your business.",
  "voided_at": null,
  "channel": "api",
  "imported": false,
  "metadata": {
    "crm_id": "acct-1001"
  },
  "created_at": "2026-03-14T09:30:00Z",
  "customer": "cus_XXXXXXXXXXXX01",
  "customer_name": "Maya Castillo",
  "customer_email": "maya@example.com",
  "items": [
    {
      "id": "cni_XXXXXXXXXXXX01",
      "description": "Everything a growing team needs.",
      "amount_minor": 2900,
      "period_start": "2026-03-14T09:30:00Z",
      "period_end": "2026-04-14T09:30:00Z"
    }
  ],
  "discounts": [
    {
      "object": "discount",
      "type": "promotional_credits",
      "amount_minor": 2900,
      "description": "Promotional"
    }
  ],
  "taxes": [
    {
      "object": "taxe",
      "description": "IGST",
      "amount_minor": 2900
    }
  ],
  "gateway_refundable_minor": 2900,
  "allocations": [
    {
      "object": "allocation",
      "invoice": "inv_XXXXXXXXXXXX01",
      "amount_minor": 2900,
      "allocated_at": "2026-03-14T09:30:00Z"
    }
  ],
  "refunds": [
    {
      "object": "refund",
      "transaction": "txn_XXXXXXXXXXXX01",
      "status": "active",
      "amount_minor": 2900,
      "currency": "USD",
      "offline": false
    }
  ]
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Over-credit / not refundable"
  }
}
```

```json [409 Conflict]
{
  "error": {
    "type": "idempotency_error",
    "message": "Idempotency-Key conflict — the key is already in flight, or was reused with a different request payload."
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.