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

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

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