Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks
Sandboxes

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

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

  • 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

  • amountintegerRequired conditionally

  • credit_amountinteger

  • effective_attimestamp

  • email_typeenum

  • out_of_band_amountinteger

  • refund_amountinteger

  • refundsarray of objects

  • shipping_costobjectRequired conditionally

Returns

Returns a credit note object if the call succeeded.

POST /v1/credit_notes
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
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
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
        }
      ]
    }
  ]
}

Retrieve a credit note preview's line items 

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

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.

  • 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

  • amountintegerRequired conditionally

  • credit_amountinteger

  • effective_attimestamp

  • email_typeenum

  • ending_beforestring

  • limitinteger

  • out_of_band_amountinteger

  • refund_amountinteger

  • refundsarray of objects

  • shipping_costobjectRequired conditionally

  • starting_afterstring

Returns

Returns a list of line_item objects.

GET /v1/credit_notes/preview/lines
curl -G https://api.stripe.com/v1/credit_notes/preview/lines \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d invoice=in_1Nn8592eZvKYlo2Ci4yFC46f
Response
{
  "id": "cn_1Nn7fB2eZvKYlo2CuJ0wZBlA",
  "object": "credit_note",
  "amount": 1451,
  "amount_shipping": 0,
  "created": 1693952641,
  "currency": "usd",
  "customer": "cus_9s6XKzkNRiz8i3",
  "customer_balance_transaction": null,
  "discount_amount": 0,
  "discount_amounts": [],
  "effective_at": null,
  "invoice": "in_1Nn7fB2eZvKYlo2C7meA67Xp",
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "cnli_1Nn7fB2eZvKYlo2Cp8nLMci9",
        "object": "credit_note_line_item",
        "amount": 951,
        "description": "My First Invoice Item (created for API docs)",
        "discount_amount": 0,
        "discount_amounts": [],
        "invoice_line_item": "il_1Nn7fB2eZvKYlo2ChKG2H1tv",
        "livemode": false,
        "quantity": 1,
        "tax_rates": [
          {
            "id": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD",
            "object": "tax_rate",
            "active": true,
            "country": "DE",
            "created": 1693952641,
            "description": "VAT Germany",
            "display_name": "VAT",
            "effective_percentage": null,
            "inclusive": false,
            "jurisdiction": "DE",
            "livemode": false,
            "metadata": {},
            "percentage": 19,
            "state": null,
            "tax_type": "vat"
          }
        ],
        "taxes": [
          {
            "amount": 152,
            "tax_behavior": "exclusive",
            "tax_rate_details": {
              "tax_rate": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD"
            },
            "taxability_reason": "not_available",
            "taxable_amount": 799,
            "type": "tax_rate_details"
          }
        ],
        "type": "invoice_line_item",
        "unit_amount": null,
        "unit_amount_decimal": null
      },
      {
        "id": "cnli_1Nn7fB2eZvKYlo2C7OxQLHdz",
        "object": "credit_note_line_item",
        "amount": 500,
        "description": "Service credit",
        "discount_amount": 0,
        "discount_amounts": [],
        "livemode": false,
        "quantity": 1,
        "tax_rates": [],
        "taxes": [],
        "type": "custom_line_item",
        "unit_amount": 500,
        "unit_amount_decimal": "500"
      }
    ],
    "has_more": false,
    "url": "/v1/credit_notes/cn_1Nn7fB2eZvKYlo2CuJ0wZBlA/lines"
  },
  "livemode": false,
  "memo": null,
  "metadata": {},
  "number": "ABCD-1234-CN-01",
  "out_of_band_amount": null,
  "pdf": "https://pay.stripe.com/credit_notes/acct_1032D82eZvKYlo2C/cnst_123456789/pdf?s=ap",
  "reason": null,
  "refund": null,
  "shipping_cost": null,
  "status": "issued",
  "subtotal": 1451,
  "subtotal_excluding_tax": 1451,
  "total": 1451,
  "total_excluding_tax": null,
  "total_taxes": [
    {
      "amount": 152,
      "tax_behavior": "exclusive",
      "tax_rate_details": {
        "tax_rate": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD"
      },
      "taxability_reason": "not_available",
      "taxable_amount": 799,
      "type": "tax_rate_details"
    }
  ],
  "type": "pre_payment",
  "voided_at": null
}