Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.

The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer.

A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer. Coupons may be applied to [subscriptions](https://stripe.com/docs/api#subscriptions), [invoices](https://stripe.com/docs/api#invoices),
[checkout sessions](https://stripe.com/docs/api/checkout/sessions), [quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge) or [payment intents](https://stripe.com/docs/api/payment_intents).

Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.

Time at which the object was created. Measured in seconds since the Unix epoch.

If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.

Coupons defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).

One of `forever`, `once`, and `repeating`. Describes how long a customer who applies this coupon will get the discount.

If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.

Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.

Name of the coupon displayed to customers on for instance invoices or receipts.

String representing the object's type. Objects of the same type share the same value.

Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.

Date after which the coupon can no longer be redeemed.

Number of times this coupon has been applied to a customer.

Taking account of the above properties, whether this coupon can still be applied to a customer.

Coupon

Date at which the promotion code can no longer be redeemed.

Maximum number of times this promotion code can be redeemed.

Promotion code restrictions defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).

A Boolean indicating if the Promotion Code should only be redeemed for Customers without any successful payments or invoices

Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work).

Three-letter [ISO code](https://stripe.com/docs/currencies) for minimum_amount

PromotionCodesResourceRestrictions

Number of times this promotion code has been used.

Promotion Codes

_search

Balance Transactions

Balance

This is an object representing a Stripe account. You can retrieve it to see
properties on the account like its current requirements or if the account is
enabled to make live charges or receive payouts.

For Custom accounts, the properties below are always returned. For other accounts, some properties are returned until that
account has started to go through Connect Onboarding. Once you create an [Account Link](https://stripe.com/docs/api/account_links)
for a Standard or Express account, some parameters are no longer returned. These are marked as **Custom Only** or **Custom and Express**
below. Learn about the differences [between accounts](https://stripe.com/docs/connect/accounts).

Account

The name of the person or business that owns the bank account.

The type of entity that holds the account. This can be either `individual` or `company`.

The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`.

A set of available payout methods for this bank account. Only values from this set should be passed as the `method` when creating a payout.

Name of the bank associated with the routing number (e.g., `WELLS FARGO`).

Two-letter ISO code representing the country the bank account is located in.

Three-letter [ISO code for the currency](https://stripe.com/docs/payouts) paid out to the bank account.

DeletedCustomer

Whether this bank account is the default external account for its currency.

Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.

Fields that need to be collected to keep the external account enabled. If not collected by `current_deadline`, these fields appear in `past_due` as well, and the account is disabled.

Fields that are `currently_due` and need to be collected again because validation or verification failed.

Fields that weren't collected by `current_deadline`. These fields need to be collected to enable the external account.

Fields that may become required depending on the results of verification or review. Will be an empty array unless an asynchronous verification is pending. If verification fails, these fields move to `eventually_due`, `currently_due`, or `past_due`.

ExternalAccountRequirements

The last four digits of the bank account number.

The routing transit number for the bank account.

For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, or `errored`. A bank account that hasn't had any activity or validation performed is `new`. If Stripe can determine that the bank account exists, its status will be `validated`. Note that there often isn’t enough information to know (e.g., for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be `verified`. If the verification failed for any reason, such as microdeposit failure, the status will be `verification_failed`. If a payout sent to this bank account fails, we'll set the status to `errored` and will not continue to send [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) until the bank details are updated.

For external accounts, possible values are `new`, `errored` and `verification_failed`. If a payouts fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In India, if we can't [verify the owner of the bank account](https://support.stripe.com/questions/bank-account-ownership-verification), we'll set the status to `verification_failed`. Other validations aren't run against external accounts because they're only used for payouts. This means the other statuses don't apply.

Bank Accounts

Billing address country, if provided when creating card.

Address line 1 (Street address/PO Box/Company name).

If `address_line1` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.

Address line 2 (Apartment/Suite/Unit/Building).

If `address_zip` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.

A set of available payout methods for this card. Only values from this set should be passed as the `method` when creating a payout.

Card brand. Can be `American Express`, `Diners Club`, `Discover`, `Eftpos Australia`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.

Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you've collected.

Three-letter [ISO code for currency](https://stripe.com/docs/payouts). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency.

If a CVC was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`. A result of unchecked indicates that CVC was provided but hasn't been checked yet. Checks are typically performed when attaching a card to a Customer object, or when creating a charge. For more details, see [Check if a card is valid without a charge](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge).

Whether this card is the default external account for its currency.

(For tokenized numbers only.) The last four digits of the device account number.

Two-digit number representing the card's expiration month.

Four-digit number representing the card's expiration year.

Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example. For payment methods that tokenize card information (Apple Pay, Google Pay), the tokenized number might be provided instead of the underlying card number.

*As of May 1, 2021, card fingerprint in India for Connect changed to allow two fingerprints for the same card---one for India and one for the rest of the world.*

Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.

For external accounts that are cards, possible values are `new` and `errored`. If a payout fails, the status is set to `errored` and [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) are stopped until account details are updated.

If the card number is tokenized, this is the method that was used. Can be `android_pay` (includes Google Pay), `apple_pay`, `masterpass`, `visa_checkout`, or null.

Cards

Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or [equivalent in charge currency](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).

Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).

Application

PlatformFee

The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://stripe.com/docs/connect/direct-charges#collecting-fees) for details.

Balance transactions represent funds moving through your Stripe account.
Stripe creates them for every type of transaction that enters or leaves your Stripe account balance.

Related guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)

BalanceTransaction

Billing phone number (including extension).

billing_details

The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined.

Whether to immediately capture the charge. Defaults to true. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire after a set number of days (7 by default). For more information, see the authorizing charges and settling later documentation.

If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.

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

An arbitrary string attached to the object. Often useful for displaying to users.

Error code explaining reason for charge failure if available (see [the errors section](https://stripe.com/docs/error-codes) for a list of codes).

Message to user further explaining reason for charge failure if available.

Assessments from Stripe. If set, the value is `fraudulent`.

Assessments reported by you. If set, possible values of are `safe` and `fraudulent`.

ChargeFraudDetails

Invoices are statements of amounts owed by a customer, and are either
generated one-off, or generated periodically from a subscription.

They contain [invoice items](https://stripe.com/docs/api#invoiceitems), and proration adjustments
that may be caused by subscription upgrades/downgrades (if necessary).

If your invoice is configured to be billed through automatic charges,
Stripe automatically finalizes your invoice and attempts payment. Note
that finalizing the invoice,
[when automatic](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection), does
not happen immediately as the invoice is created. Stripe waits
until one hour after the last webhook was successfully sent (or the last
webhook timed out after failing). If you (and the platforms you may have
connected to) have no webhooks configured, Stripe waits one hour after
creation to finalize the invoice.

If your invoice is configured to be billed by sending an email, then based on your
[email settings](https://dashboard.stripe.com/account/billing/automatic),
Stripe will email the invoice to your customer and await payment. These
emails can contain a link to a hosted page to pay the invoice.

Stripe applies any customer credit on the account before determining the
amount due for the invoice (i.e., the amount that will be actually
charged). If the amount due for the invoice is less than Stripe's [minimum allowed charge
per currency](/docs/currencies#minimum-and-maximum-charge-amounts), the
invoice is automatically marked paid, and we add the amount due to the
customer's credit balance which is applied to the next invoice.

More details on the customer's credit balance are
[here](https://stripe.com/docs/billing/customer/balance).

Related guide: [Send invoices to customers](https://stripe.com/docs/billing/invoices/sending)

Invoice

Possible values are `approved_by_network`, `declined_by_network`, `not_sent_to_network`, and `reversed_after_approval`. The value `reversed_after_approval` indicates the payment was [blocked by Stripe](https://stripe.com/docs/declines#blocked-payments) after bank authorization, and may temporarily appear as "pending" on a cardholder's statement.

An enumerated value providing a more detailed explanation of the outcome's `type`. Charges blocked by Radar's default block rule have the value `highest_risk_level`. Charges placed in review by Radar's default review rule have the value `elevated_risk_level`. Charges authorized, blocked, or placed in review by custom rules have the value `rule`. See [understanding declines](https://stripe.com/docs/declines) for more details.

Stripe Radar's evaluation of the riskiness of the payment. Possible values for evaluated payments are `normal`, `elevated`, `highest`. For non-card payments, and card-based payments predating the public assignment of risk levels, this field will have the value `not_assessed`. In the event of an error in the evaluation, this field will have the value `unknown`. This field is only available with Radar.

Stripe Radar's evaluation of the riskiness of the payment. Possible values for evaluated payments are between 0 and 100. For non-card payments, card-based payments predating the public assignment of risk scores, or in the event of an error during evaluation, this field will not be present. This field is only available with Radar for Fraud Teams.

A human-readable description of the outcome type and reason, designed for you (the recipient of the payment), not your customer.

Possible values are `authorized`, `manual_review`, `issuer_declined`, `blocked`, and `invalid`. See [understanding declines](https://stripe.com/docs/declines) and [Radar reviews](https://stripe.com/docs/radar/reviews) for details.

ChargeOutcome

`true` if the charge succeeded, or was successfully authorized for later capture.

A PaymentIntent guides you through the process of collecting a payment from your customer.
We recommend that you create exactly one PaymentIntent for each order or
customer session in your system. You can reference the PaymentIntent later to
see the history of payment attempts for a particular session.

A PaymentIntent transitions through
[multiple statuses](https://stripe.com/docs/payments/intents#intent-statuses)
throughout its lifetime as it interfaces with Stripe.js to perform
authentication flows and ultimately creates at most one successful charge.

Related guide: [Payment Intents API](https://stripe.com/docs/payments/payment-intents)

PaymentIntent

ID of the payment method used in this charge.

The type of transaction-specific details of the payment method used in the payment, one of `ach_credit_transfer`, `ach_debit`, `acss_debit`, `alipay`, `au_becs_debit`, `bancontact`, `card`, `card_present`, `eps`, `giropay`, `ideal`, `klarna`, `multibanco`, `p24`, `sepa_debit`, `sofort`, `stripe_account`, or `wechat`.
An additional hash is included on `payment_method_details` with a name matching this value.
It contains information specific to the payment method.

payment_method_details

Options to configure Radar. See [Radar Session](https://stripe.com/docs/radar/radar-session) for more information.

A [Radar Session](https://stripe.com/docs/radar/radar-session) is a snapshot of the browser metadata and device details that help Radar make more accurate predictions on your payments.

RadarRadarOptions

This is the email address that the receipt for this charge was sent to.

This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.

This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.

Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.

A list of refunds that have been applied to the charge.

True if this list has another page of items after this one that can be fetched.

String representing the object's type. Objects of the same type share the same value. Always has the value `list`.

RefundList

Reviews can be used to supplement automated fraud detection with human expertise.

Learn more about [Radar](/radar) and reviewing payments
[here](https://stripe.com/docs/radar/reviews).

RadarReview

The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

Shipping

A `Transfer` object is created when you move funds between Stripe accounts as
part of Connect.

Before April 6, 2017, transfers also represented movement of funds from a
Stripe account to a card or bank account. This behavior has since been split
out into a [Payout](https://stripe.com/docs/api#payout_object) object, with corresponding payout endpoints. For more
information, read about the
[transfer/payout split](https://stripe.com/docs/transfer-payout-split).

Related guide: [Creating separate charges and transfers](https://stripe.com/docs/connect/separate-charges-and-transfers)

Transfer

For card charges, use `statement_descriptor_suffix` instead. Otherwise, you can use this value as the complete description of a charge on your customers’ statements. Must contain at least one letter, maximum 22 characters.

Provides information about the charge that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor.

The status of the payment is either `succeeded`, `pending`, or `failed`.

The amount transferred to the destination account, if specified. By default, the entire charge amount is transferred to the destination account.

ChargeTransferData

A string that identifies this transaction as part of a group. See the [Connect documentation](https://stripe.com/docs/connect/separate-charges-and-transfers#transfer-options) for details.

Charges

A list of product IDs this coupon applies to

CouponAppliesTo

CouponCurrencyOption

Coupons

This is the sum of all the shipping amounts.

Each customer has a [Balance](https://stripe.com/docs/api/customers/object#customer_object-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](https://stripe.com/docs/api/customers/update),
or by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`.

Related guide: [Customer balance](https://stripe.com/docs/billing/customer/balance)

CustomerBalanceTransaction

The integer amount in cents (or local equivalent) representing the total amount of discount that was credited.

The aggregate amounts calculated per discount for all line items.

DiscountsResourceDiscountAmount

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.

Customer-facing text that appears on the credit note PDF.

A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.

Amount that was credited outside of Stripe.

The link to download the PDF of the credit note.

Reason for issuing this credit note, one of `duplicate`, `fraudulent`, `order_change`, or `product_unsatisfactory`

Total shipping cost before any taxes are applied.

Total tax amount applied due to shipping costs. If no tax was applied, defaults to 0.

Total shipping cost after taxes are applied.

The ID of the ShippingRate for this invoice.

InvoicesShippingCost

Status of this credit note, one of `issued` or `void`. Learn more about [voiding credit notes](https://stripe.com/docs/billing/invoices/credit-notes#voiding).

The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding exclusive tax and invoice level discounts.

The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding all tax and invoice level discounts.

The aggregate amounts calculated per tax rate for all line items.

CreditNoteTaxAmount

The integer amount in cents (or local equivalent) representing the total amount of the credit note, including tax and all discount.

The integer amount in cents (or local equivalent) representing the total amount of the credit note, excluding tax, but including discounts.

Type of this credit note, one of `pre_payment` or `post_payment`. A `pre_payment` credit note means it was issued when the invoice was open. A `post_payment` credit note means it was issued when the invoice was paid.

The time that the credit note was voided.

Credit Notes

City, district, suburb, town, or village.

Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

Address line 1 (e.g., street, PO Box, or company name).

Address line 2 (e.g., apartment, suite, unit, or building).

Address

The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.

A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.

A hash of all cash balances available to this customer. You cannot delete a customer with any cash balances, even if the balance is 0. Amounts are represented in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal).

The ID of the customer whose cash balance this object represents.

cash_balance

Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.

`Source` objects allow you to accept a variety of payment methods. They
represent a customer's payment instrument, and can be used with the Stripe API
just like a `Card` object: once chargeable, they can be charged, or can be
attached to customers.

Stripe doesn't recommend using the deprecated [Sources API](https://stripe.com/docs/api/sources).
We recommend that you adopt the [PaymentMethods API](https://stripe.com/docs/api/payment_methods).
This newer API provides access to our latest features and payment method types.

Related guides: [Sources API](https://stripe.com/docs/sources) and [Sources & Customers](https://stripe.com/docs/sources/customers).

Source

Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.

If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn't reset to `false`.

If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.

A discount represents the actual application of a [coupon](https://stripe.com/docs/api#coupons) or [promotion code](https://stripe.com/docs/api#promotion_codes).
It contains information about when the discount began, when it will end, and what it is applied to.

Related guide: [Applying discounts to subscriptions](https://stripe.com/docs/billing/subscriptions/discounts)

The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Will not be present for subscription mode.

If the coupon has a duration of `repeating`, the date that this discount will end. If the coupon has a duration of `once` or `forever`, this attribute will be null.

The ID of the discount object. Discounts cannot be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.

The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.

The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item.

The subscription that this coupon is applied to, if it is applied to a particular subscription.

Discount

The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.

The prefix for the customer used to generate unique invoice numbers.

Default custom fields to be displayed on invoices for this customer.

The customer's full name or business name.

The suffix of the customer's next invoice number (for example, 0001).

The customer's preferred locales (languages), ordered by preference.

ApmsSourcesSourceList

The customer's current subscriptions, if any.

SubscriptionList

Surfaces if automatic tax computation is possible given the current customer location information.

A recent IP address of the customer used for tax reporting and tax location inference.

Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.

TaxIDsList

A test clock enables deterministic control over objects in testmode. With a test clock, you can create
objects at a frozen time in the past or future, and advance to a specific future time to observe webhooks and state changes. After the clock advances,
you can either validate the current state of your scenario (and test your assumptions), change the current state of your scenario (and test more complex scenarios), or keep advancing forward in time.

TestClock

Customers

Amount (in the `currency` specified) of the invoice item. This should always be equal to `unit_amount * quantity`.

If true, discounts will apply to this invoice item. Always false for prorations.

Stripe API Integration Profile

How to work with Promotion Codes in Stripe API

Operations on Promotion Codes Collection

See Related Collections

Build every single integration your customers need with AI

Field Name	API Key	Type	Description
Active	active	boolean	Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.
Code	code	string	The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer.
Coupon	coupon	object	A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to [subscriptions](https://stripe.com/docs/api#subscriptions), [invoices](https://stripe.com/docs/api#invoices), [checkout sessions](https://stripe.com/docs/api/checkout/sessions), [quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge) or [payment intents](https://stripe.com/docs/api/payment_intents).
Amount Off	coupon.amount_off	integer	Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.
Created	coupon.created	integer	Time at which the object was created. Measured in seconds since the Unix epoch.