List all credit notes

Returns a list of credit notes.

Parameters

invoicestring
Only return credit notes for the invoice specified by this invoice ID.

More parameters

createdobject

customerstring

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit credit notes, starting after credit note starting_after. Each entry in the array is a separate credit note object. If no more credit notes are available, the resulting array will be empty.

GET /v1/credit_notes

Server-side language

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

Response

{
  "object": "list",
  "url": "/v1/credit_notes",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}

Preview a credit note

Get a preview of a credit note without creating it.

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.

GET /v1/credit_notes/preview

Server-side language

curl -G https://api.stripe.com/v1/credit_notes/preview \
  -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
}

Void a credit note

Marks a credit note as void. Learn more about voiding credit notes.

Parameters

No parameters.

Returns

Returns the voided credit note object if the call succeeded.

POST /v1/credit_notes/:id/void

Server-side language

curl -X POST https://api.stripe.com/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/void \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

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": "void",
  "subtotal": 1099,
  "subtotal_excluding_tax": 1099,
  "total": 1099,
  "total_excluding_tax": 1099,
  "total_taxes": [],
  "type": "pre_payment",
  "voided_at": 1681750959
}

Customer Balance Transaction

Each customer has a Balance value, which denotes a debit or credit that’s automatically applied to their next invoice upon finalization. You may modify the value directly by using the update customer API, or by creating a Customer Balance Transaction, which increments or decrements the customer’s balance by the specified amount.

Related guide: Customer balance

Endpoints

POST/v1/customers/:id/balance_transactions

POST/v1/customers/:id/balance_transactions/:id

GET/v1/customers/:id/balance_transactions/:id

GET/v1/customers/:id/balance_transactions

Customer Portal Session

The Billing customer portal is a Stripe-hosted UI for subscription and billing management.

A portal configuration describes the functionality and features that you want to provide to your customers through the portal.

A portal session describes the instantiation of the customer portal for a particular customer. By visiting the session’s URL, the customer can manage their subscriptions and billing details. For security reasons, sessions are short-lived and will expire if the customer does not visit the URL. Create sessions on-demand when customers intend to manage their subscriptions and billing details.

Related guide: Customer management

Endpoints

POST/v1/billing_portal/sessions

Was this page helpful?

Yes No

Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

List all credit notes

Parameters

invoicestring

More parametersExpand all

createdobject

customerstring

ending_beforestring

limitinteger

starting_afterstring

Returns

Preview a credit note

Parameters

invoicestringRequired

linesarray of objectsRequired conditionally

memostring

metadataobject

reasonenum

More parametersExpand all

amountintegerRequired conditionally

credit_amountinteger

effective_attimestamp

email_typeenum

out_of_band_amountinteger

refund_amountinteger

refundsarray of objects

shipping_costobjectRequired conditionally

Returns

Void a credit note

Parameters

Returns

Customer Balance Transaction

Customer Portal Session

More parameters

More parameters