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 objectsRequired conditionally

  Line items that make up the credit note. One of amount, lines, or shipping_cost must be provided.

  Hide child parameters

  • lines.typeenumRequired

    Type of the credit note line item, one of invoice_line_item or custom_line_item

    Possible enum values

    custom_line_item

    invoice_line_item

  • lines.amountinteger

    The line item amount to credit. Only valid when type is invoice_line_item. If invoice is set up with automatic_tax[enabled]=true, this amount is tax exclusive

  • lines.descriptionstring

    The description of the credit note line item. Only valid when the type is custom_line_item.

  • lines.invoice_line_itemstring

    The invoice line item to credit. Only valid when the type is invoice_line_item.

  • lines.quantityinteger

    The line item quantity to credit.

  • lines.tax_amountsarray of objects

    A list of up to 10 tax amounts for the credit note line item. Cannot be mixed with tax_rates.

    Hide child parameters

    • lines.tax_amounts.amountintegerRequired

      The amount, in cents, of the tax.

    • lines.tax_amounts.tax_ratestringRequired

      The id of the tax rate for this tax amount. The tax rate must have been automatically created by Stripe.

    • lines.tax_amounts.taxable_amountintegerRequired

      The amount on which tax is calculated, in cents.

  • lines.tax_ratesarray of strings

    The tax rates which apply to the credit note line item. Only valid when the type is custom_line_item and cannot be mixed with tax_amounts.

  • lines.unit_amountinteger

    The integer unit amount in cents of the credit note line item. This unit_amount will be multiplied by the quantity to get the full amount to credit for this line item. Only valid when type is custom_line_item.

  • lines.unit_amount_decimalstring

    Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

• 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 Credit issued for a duplicate payment or charge

  fraudulent Credit note issued for fraudulent activity

  order_change Credit note issued for order change

  product_unsatisfactory Credit note issued for unsatisfactory product

More parameters

Collapse all

• amountintegerRequired conditionally

  The integer amount in cents representing the total amount of the credit note. One of amount, lines, or shipping_cost must be provided.

• credit_amountinteger

  The integer amount in cents representing the amount to credit the customer’s balance, which will be automatically applied to their next invoice.

• effective_attimestamp

  The date when this credit note is in effect. Same as created unless overwritten. When defined, this value replaces the system-generated ‘Date of issue’ printed on the credit note PDF.

• email_typeenum

  Type of email to send to the customer, one of credit_note or none and the default is credit_note.

  Possible enum values

  credit_note credit note email

  none no email

• out_of_band_amountinteger

  The integer amount in cents representing the amount that is credited outside of Stripe.

• refund_amountinteger

  The integer amount in cents representing the amount to refund. If set, a refund will be created for the charge associated with the invoice.

• refundsarray of objects

  Refunds to link to this credit note.

  Hide child parameters

  • refunds.amount_refundedinteger

    Amount of the refund that applies to this credit note, in cents. Defaults to the entire refund amount.

  • refunds.refundstring

    ID of an existing refund to link this credit note to. Required when type is refund.

• shipping_costobjectRequired conditionally

  When shipping_cost contains the shipping_rate from the invoice, the shipping_cost is included in the credit note. One of amount, lines, or shipping_cost must be provided.

  Hide child parameters

  • shipping_cost.shipping_ratestringRequired if shipping cost should be included for credit note

    The ID of the shipping rate to use for this order.