The Credit Note object

Attributes

idstring
Unique identifier for the object.

currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.

invoicestringExpandable
ID of the invoice.

linesobject
Line items that make up the credit note

memonullable string
Customer-facing text that appears on the credit note PDF.

metadatanullable object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

reasonnullable enum
Reason for issuing this credit note, one of duplicate, fraudulent, order_change, or product_unsatisfactory
Possible enum values
duplicate
fraudulent
order_change
product_unsatisfactory

statusenum
Status of this credit note, one of issued or void. Learn more about voiding credit notes.
Possible enum values
issued
The credit note has been issued.
void
The credit note has been voided.

subtotalinteger
The integer amount in cents representing the amount of the credit note, excluding exclusive tax and invoice level discounts.

totalinteger
The integer amount in cents representing the total amount of the credit note, including tax and all discount.

More attributes

objectstring

amountinteger

amount_shippinginteger

createdtimestamp

customerstringExpandable

customer_balance_transactionnullable stringExpandable

discount_amountintegerDeprecated

discount_amountsarray of objects

effective_atnullable timestamp

livemodeboolean

numberstring

out_of_band_amountnullable integer

pdfstring

post_payment_amountinteger

pre_payment_amountinteger

pretax_credit_amountsarray of objects

refundsarray of objects

shipping_costnullable object

subtotal_excluding_taxnullable integer

total_excluding_taxnullable integer

total_taxesnullable array of objects

typeenum

voided_atnullable timestamp

The Credit Note object

{
  "id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
  "object": "credit_note",
  "amount": 1099,
  "amount_shipping": 0,
  "created": 1681750958,
  "currency": "usd",
  "customer": "cus_NjLgPhUokHubJC",
  "customer_balance_transaction": null,
  "discount_amount": 0,
  "discount_amounts": [],
  "invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
        "object": "credit_note_line_item",
        "amount": 1099,
        "description": "T-shirt",
        "discount_amount": 0,
        "discount_amounts": [],
        "invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
        "livemode": false,
        "quantity": 1,
        "tax_rates": [],
        "taxes": [],
        "type": "invoice_line_item",
        "unit_amount": 1099,
        "unit_amount_decimal": "1099"
      }
    ],
    "has_more": false,
    "url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
  },
  "livemode": false,
  "memo": null,
  "metadata": {},
  "number": "C9E0C52C-0036-CN-01",
  "out_of_band_amount": null,
  "pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
  "pre_payment_amount": 1099,
  "post_payment_amount": 0,
  "reason": null,
  "refunds": [],
  "shipping_cost": null,
  "status": "issued",
  "subtotal": 1099,
  "subtotal_excluding_tax": 1099,
  "total": 1099,
  "total_excluding_tax": 1099,
  "total_taxes": [],
  "type": "pre_payment",
  "voided_at": null
}

The Credit Note Line Item object

Attributes

idstring
Unique identifier for the object.

objectstring
String representing the object’s type. Objects of the same type share the same value.

amountinteger
The integer amount in cents representing the gross amount being credited for this line item, excluding (exclusive) tax and discounts.

descriptionnullable string
Description of the item being credited.

discount_amountintegerDeprecated
The integer amount in cents representing the discount being credited for this line item.

discount_amountsarray of objects
The amount of discount calculated per discount for this line item

invoice_line_itemnullable string
ID of the invoice line item being credited

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

pretax_credit_amountsarray of objects
The pretax credit amounts (ex: discount, credit grants, etc) for this line item.

quantitynullable integer
The number of units of product being credited.

tax_ratesarray of objects
The tax rates which apply to the line item.

taxesnullable array of objects
The tax information of the line item.

typeenum
The type of the credit note line item, one of invoice_line_item or custom_line_item. When the type is invoice_line_item there is an additional invoice_line_item property on the resource the value of which is the id of the credited line item on the invoice.
Possible enum values
custom_line_item
invoice_line_item

unit_amountnullable integer
The cost of each unit of product being credited.

unit_amount_decimalnullable decimal string
Same as unit_amount, but contains a decimal value with at most 12 decimal places.

The Credit Note Line Item object

{
  "id": "cnli_1NPtOx2eZvKYlo2CBH1NpUsU",
  "object": "credit_note_line_item",
  "amount": 749,
  "description": "My First Invoice Item (created for API docs)",
  "discount_amount": 0,
  "discount_amounts": [],
  "invoice_line_item": "il_1NPtOx2eZvKYlo2CAUuq0WVl",
  "livemode": false,
  "quantity": 1,
  "taxes": [],
  "tax_rates": [],
  "type": "invoice_line_item",
  "unit_amount": null,
  "unit_amount_decimal": null
}

Create a credit note

Issue a credit note to adjust the amount of a finalized invoice. A credit note will first reduce the invoice’s amount_remaining (and amount_due), but not below zero. This amount is indicated by the credit note’s pre_payment_amount. The excess amount is indicated by post_payment_amount, and it can result in any combination of the following:

Refunds: create a new refund (using refund_amount) or link existing refunds (using refunds).
Customer balance credit: credit the customer’s balance (using credit_amount) which will be automatically applied to their next invoice when it’s finalized.
Outside of Stripe credit: record the amount that is or will be credited outside of Stripe (using out_of_band_amount).

The sum of refunds, customer balance credits, and outside of Stripe credits must equal the post_payment_amount.

You may issue multiple credit notes for an invoice. Each credit note may increment the invoice’s pre_payment_credit_notes_amount, post_payment_credit_notes_amount, or both, depending on the invoice’s amount_remaining at the time of credit note creation.

Parameters

invoicestringRequired
ID of the invoice.

linesarray of objects
Line items that make up the credit note.

memostring
The credit note’s memo appears on the credit note PDF.

metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

reasonenum
Reason for issuing this credit note, one of duplicate, fraudulent, order_change, or product_unsatisfactory
Possible enum values
duplicate
fraudulent
order_change
product_unsatisfactory

More parameters

amountinteger

credit_amountinteger

effective_attimestamp

email_typeenum

out_of_band_amountinteger

refund_amountinteger

refundsarray of objects

shipping_costobject

Returns

Returns a credit note object if the call succeeded.

POST /v1/credit_notes

Server-side language

curl https://api.stripe.com/v1/credit_notes \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d invoice=in_1MxvRkLkdIwHu7ixABNtI99m

Response

{
  "id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
  "object": "credit_note",
  "amount": 1099,
  "amount_shipping": 0,
  "created": 1681750958,
  "currency": "usd",
  "customer": "cus_NjLgPhUokHubJC",
  "customer_balance_transaction": null,
  "discount_amount": 0,
  "discount_amounts": [],
  "invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
        "object": "credit_note_line_item",
        "amount": 1099,
        "description": "T-shirt",
        "discount_amount": 0,
        "discount_amounts": [],
        "invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
        "livemode": false,
        "quantity": 1,
        "tax_rates": [],
        "taxes": [],
        "type": "invoice_line_item",
        "unit_amount": 1099,
        "unit_amount_decimal": "1099"
      }
    ],
    "has_more": false,
    "url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
  },
  "livemode": false,
  "memo": null,
  "metadata": {},
  "number": "C9E0C52C-0036-CN-01",
  "out_of_band_amount": null,
  "pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
  "pre_payment_amount": 1099,
  "post_payment_amount": 0,
  "reason": null,
  "refunds": [],
  "shipping_cost": null,
  "status": "issued",
  "subtotal": 1099,
  "subtotal_excluding_tax": 1099,
  "total": 1099,
  "total_excluding_tax": 1099,
  "total_taxes": [],
  "type": "pre_payment",
  "voided_at": null
}

Update a credit note

Updates an existing credit note.

Parameters

memostring
Credit note memo.

metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

Returns the updated credit note object if the call succeeded.

POST /v1/credit_notes/:id

Server-side language

curl https://api.stripe.com/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735

Response

{
  "id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
  "object": "credit_note",
  "amount": 1099,
  "amount_shipping": 0,
  "created": 1681750958,
  "currency": "usd",
  "customer": "cus_NjLgPhUokHubJC",
  "customer_balance_transaction": null,
  "discount_amount": 0,
  "discount_amounts": [],
  "invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
        "object": "credit_note_line_item",
        "amount": 1099,
        "description": "T-shirt",
        "discount_amount": 0,
        "discount_amounts": [],
        "invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
        "livemode": false,
        "quantity": 1,
        "tax_rates": [],
        "taxes": [],
        "type": "invoice_line_item",
        "unit_amount": 1099,
        "unit_amount_decimal": "1099"
      }
    ],
    "has_more": false,
    "url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
  },
  "livemode": false,
  "memo": null,
  "metadata": {
    "order_id": "6735"
  },
  "number": "C9E0C52C-0036-CN-01",
  "out_of_band_amount": null,
  "pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
  "pre_payment_amount": 1099,
  "post_payment_amount": 0,
  "reason": null,
  "refunds": [],
  "shipping_cost": null,
  "status": "issued",
  "subtotal": 1099,
  "subtotal_excluding_tax": 1099,
  "total": 1099,
  "total_excluding_tax": 1099,
  "total_taxes": [],
  "type": "pre_payment",
  "voided_at": null
}

Retrieve a credit note's line items

When retrieving a credit note, you’ll get a lines property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

No parameters.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

Returns a list of line_item objects.

GET /v1/credit_notes/:id/lines

Server-side language

curl -G https://api.stripe.com/v1/credit_notes/cn_1NPtPy2eZvKYlo2CPaEMGMY8/lines \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/credit_notes/cn_1NPtPy2eZvKYlo2CPaEMGMY8/lines",
  "has_more": false,
  "data": [
    {
      "object": "list",
      "url": "/v1/credit_notes/cn_1Nn7fB2eZvKYlo2CuJ0wZBlA/lines",
      "has_more": false,
      "data": [
        {
          "id": "cnli_1Nn7fB2eZvKYlo2COYgPG88j",
          "object": "credit_note_line_item",
          "amount": 799,
          "description": "My First Invoice Item (created for API docs)",
          "discount_amount": 0,
          "discount_amounts": [],
          "invoice_line_item": "il_1Nn7fB2eZvKYlo2C3GKZP9wi",
          "livemode": false,
          "quantity": 1,
          "tax_rates": [],
          "taxes": [],
          "type": "invoice_line_item",
          "unit_amount": null,
          "unit_amount_decimal": null
        }
      ]
    }
  ]
}

The Credit Note object

Attributes

idstring

currencyenum

invoicestringExpandable

linesobject

memonullable string

metadatanullable object

reasonnullable enum

statusenum

subtotalinteger

totalinteger

More attributesExpand all

objectstring

amountinteger

amount_shippinginteger

createdtimestamp

customerstringExpandable

customer_balance_transactionnullable stringExpandable

discount_amountintegerDeprecated

discount_amountsarray of objects

effective_atnullable timestamp

livemodeboolean

numberstring

out_of_band_amountnullable integer

pdfstring

post_payment_amountinteger

pre_payment_amountinteger

pretax_credit_amountsarray of objects

refundsarray of objects

shipping_costnullable object

subtotal_excluding_taxnullable integer

total_excluding_taxnullable integer

total_taxesnullable array of objects

typeenum

voided_atnullable timestamp

The Credit Note Line Item object

Attributes

idstring

objectstring

amountinteger

descriptionnullable string

discount_amountintegerDeprecated

discount_amountsarray of objects

invoice_line_itemnullable string

livemodeboolean

pretax_credit_amountsarray of objects

quantitynullable integer

tax_ratesarray of objects

taxesnullable array of objects

typeenum

unit_amountnullable integer

unit_amount_decimalnullable decimal string

Create a credit note

Parameters

invoicestringRequired

linesarray of objects

memostring

metadataobject

reasonenum

More parametersExpand all

amountinteger

credit_amountinteger

effective_attimestamp

email_typeenum

out_of_band_amountinteger

refund_amountinteger

refundsarray of objects

shipping_costobject

Returns

Update a credit note

Parameters

memostring

metadataobject

Returns

Retrieve a credit note's line items

Parameters

More parametersExpand all

ending_beforestring

limitinteger

More attributes

More parameters

More parameters