Stripe Credit Notes API
Issue a credit note to adjust an invoice's amount after the invoice is finalized.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Credit Notes API
description: >-
Issue a credit note to adjust an invoice's amount after the invoice is
finalized.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/credit_notes:
get:
description: <p>Returns a list of credit notes.</p>
operationId: getCreditNotes
parameters:
- description: >-
Only return credit notes for the customer specified by this customer
ID.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
Only return credit notes for the invoice specified by this invoice
ID.
in: query
name: invoice
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCreditNotesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CreditNotesList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Credit Notes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Get
- Notes
post:
description: >-
<p>Issue a credit note to adjust the amount of a finalized invoice. For
a <code>status=open</code> invoice, a credit note reduces
its <code>amount_due</code>. For a <code>status=paid</code> invoice, a
credit note does not affect its <code>amount_due</code>. Instead, it can
result
in any combination of the following:</p>
<ul>
<li>Refund: create a new refund (using <code>refund_amount</code>) or
link an existing refund (using <code>refund</code>).</li>
<li>Customer balance credit: credit the customer’s balance (using
<code>credit_amount</code>) which will be automatically applied to their
next invoice when it’s finalized.</li>
<li>Outside of Stripe credit: record the amount that is or will be
credited outside of Stripe (using <code>out_of_band_amount</code>).</li>
</ul>
<p>For post-payment credit notes the sum of the refund, credit and
outside of Stripe amounts must equal the credit note total.</p>
<p>You may issue multiple credit notes for an invoice. Each credit note
will increment the invoice’s
<code>pre_payment_credit_notes_amount</code>
or <code>post_payment_credit_notes_amount</code> depending on its
<code>status</code> at the time of credit note creation.</p>
operationId: postCreditNotes
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
lines:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
shipping_cost:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCreditNotesRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credit_note'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Credit Notes
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Notes
- Post
/v1/credit_notes/preview:
get:
description: <p>Get a preview of a credit note without creating it.</p>
operationId: getCreditNotesPreview
parameters:
- description: >-
The integer amount in cents (or local equivalent) representing the
total amount of the credit note.
in: query
name: amount
required: false
schema:
type: integer
style: form
- description: >-
The integer amount in cents (or local equivalent) representing the
amount to credit the customer's balance, which will be automatically
applied to their next invoice.
in: query
name: credit_amount
required: false
schema:
type: integer
style: form
- description: >-
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.
in: query
name: effective_at
required: false
schema:
format: unix-time
type: integer
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: ID of the invoice.
in: query
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: form
- description: Line items that make up the credit note.
explode: true
in: query
name: lines
required: false
schema:
items:
properties:
amount:
type: integer
description:
maxLength: 5000
type: string
invoice_line_item:
maxLength: 5000
type: string
quantity:
type: integer
tax_amounts:
anyOf:
- items:
properties:
amount:
type: integer
tax_rate:
maxLength: 5000
type: string
taxable_amount:
type: integer
required:
- amount
- tax_rate
- taxable_amount
title: tax_amount_with_tax_rate_param
type: object
type: array
- enum:
- ''
type: string
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
type:
enum:
- custom_line_item
- invoice_line_item
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- type
title: credit_note_line_item_params
type: object
type: array
style: deepObject
- description: The credit note's memo appears on the credit note PDF.
in: query
name: memo
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) 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`.
explode: true
in: query
name: metadata
required: false
schema:
additionalProperties:
type: string
type: object
style: deepObject
- description: >-
The integer amount in cents (or local equivalent) representing the
amount that is credited outside of Stripe.
in: query
name: out_of_band_amount
required: false
schema:
type: integer
style: form
- description: >-
Reason for issuing this credit note, one of `duplicate`,
`fraudulent`, `order_change`, or `product_unsatisfactory`
in: query
name: reason
required: false
schema:
enum:
- duplicate
- fraudulent
- order_change
- product_unsatisfactory
type: string
style: form
- description: ID of an existing refund to link this credit note to.
in: query
name: refund
required: false
schema:
type: string
style: form
- description: >-
The integer amount in cents (or local equivalent) representing the
amount to refund. If set, a refund will be created for the charge
associated with the invoice.
in: query
name: refund_amount
required: false
schema:
type: integer
style: form
- description: >-
When shipping_cost contains the shipping_rate from the invoice, the
shipping_cost is included in the credit note.
explode: true
in: query
name: shipping_cost
required: false
schema:
properties:
shipping_rate:
maxLength: 5000
type: string
title: credit_note_shipping_cost
type: object
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCreditNotesPreviewRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credit_note'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Credit Notes Preview
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Get
- Notes
- Preview
/v1/credit_notes/preview/lines:
get:
description: >-
<p>When retrieving a credit note preview, you’ll get a
<strong>lines</strong> property containing the first handful of those
items. This URL you can retrieve the full (paginated) list of line
items.</p>
operationId: getCreditNotesPreviewLines
parameters:
- description: >-
The integer amount in cents (or local equivalent) representing the
total amount of the credit note.
in: query
name: amount
required: false
schema:
type: integer
style: form
- description: >-
The integer amount in cents (or local equivalent) representing the
amount to credit the customer's balance, which will be automatically
applied to their next invoice.
in: query
name: credit_amount
required: false
schema:
type: integer
style: form
- description: >-
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.
in: query
name: effective_at
required: false
schema:
format: unix-time
type: integer
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: ID of the invoice.
in: query
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: form
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: Line items that make up the credit note.
explode: true
in: query
name: lines
required: false
schema:
items:
properties:
amount:
type: integer
description:
maxLength: 5000
type: string
invoice_line_item:
maxLength: 5000
type: string
quantity:
type: integer
tax_amounts:
anyOf:
- items:
properties:
amount:
type: integer
tax_rate:
maxLength: 5000
type: string
taxable_amount:
type: integer
required:
- amount
- tax_rate
- taxable_amount
title: tax_amount_with_tax_rate_param
type: object
type: array
- enum:
- ''
type: string
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
type:
enum:
- custom_line_item
- invoice_line_item
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- type
title: credit_note_line_item_params
type: object
type: array
style: deepObject
- description: The credit note's memo appears on the credit note PDF.
in: query
name: memo
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) 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`.
explode: true
in: query
name: metadata
required: false
schema:
additionalProperties:
type: string
type: object
style: deepObject
- description: >-
The integer amount in cents (or local equivalent) representing the
amount that is credited outside of Stripe.
in: query
name: out_of_band_amount
required: false
schema:
type: integer
style: form
- description: >-
Reason for issuing this credit note, one of `duplicate`,
`fraudulent`, `order_change`, or `product_unsatisfactory`
in: query
name: reason
required: false
schema:
enum:
- duplicate
- fraudulent
- order_change
- product_unsatisfactory
type: string
style: form
- description: ID of an existing refund to link this credit note to.
in: query
name: refund
required: false
schema:
type: string
style: form
- description: >-
The integer amount in cents (or local equivalent) representing the
amount to refund. If set, a refund will be created for the charge
associated with the invoice.
in: query
name: refund_amount
required: false
schema:
type: integer
style: form
- description: >-
When shipping_cost contains the shipping_rate from the invoice, the
shipping_cost is included in the credit note.
explode: true
in: query
name: shipping_cost
required: false
schema:
properties:
shipping_rate:
maxLength: 5000
type: string
title: credit_note_shipping_cost
type: object
style: deepObject
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCreditNotesPreviewLinesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CreditNoteLinesList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Credit Notes Preview Lines
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Get
- Lines
- Notes
- Preview
/v1/credit_notes/{credit_note}/lines:
get:
description: >-
<p>When retrieving a credit note, you’ll get a <strong>lines</strong>
property containing the the first handful of those items. There is also
a URL where you can retrieve the full (paginated) list of line
items.</p>
operationId: getCreditNotesCreditNoteLines
parameters:
- in: path
name: credit_note
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCreditNotesCreditNoteLinesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CreditNoteLinesList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Credit Notes Credit Note Lines
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Get
- Lines
- Note
- Notes
/v1/credit_notes/{id}:
get:
description: <p>Retrieves the credit note object with the given identifier.</p>
operationId: getCreditNotesId
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCreditNotesIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credit_note'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Credit Notes Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Get
- Identifiers
- Notes
post:
description: <p>Updates an existing credit note.</p>
operationId: postCreditNotesId
parameters:
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCreditNotesIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credit_note'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Credit Notes Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Identifiers
- Notes
- Post
/v1/credit_notes/{id}/void:
post:
description: >-
<p>Marks a credit note as void. Learn more about <a
href="/docs/billing/invoices/credit-notes#voiding">voiding credit
notes</a>.</p>
operationId: postCreditNotesIdVoid
parameters:
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCreditNotesIdVoidRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credit_note'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Credit Notes Id Void
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Credit
- Identifiers
- Notes
- Post
- Void
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
credit_note:
description: >-
Issue a credit note to adjust an invoice's amount after the invoice is
finalized.
Related guide: [Credit
notes](https://stripe.com/docs/billing/invoices/credit-notes)
properties:
amount:
description: >-
The integer amount in cents (or local equivalent) representing the
total amount of the credit note, including tax.
type: integer
amount_shipping:
description: This is the sum of all the shipping amounts.
type: integer
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
currency:
description: >-
Three-letter [ISO currency
code](https://www.iso.org/iso-4217-currency-codes.html), in
lowercase. Must be a [supported
currency](https://stripe.com/docs/currencies).
type: string
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: ID of the customer.
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-credit-notes-api-openapi.yml