Server side integration

Stripe recommends adding an idempotency key to all POST requests. The key should be unique, such as a universally unique identifier (UUID) or a combination of customer ID and order ID for example. These keys allow you to safely retry requests if you experience a network error.

Billing overview

Stripe Billing allows you to manage recurring payments through subscriptions but you can also use it to create one-off invoices and leverage our invoice PDFs and Hosted Invoice Pages for single, ad-hoc payments.

To manage subscription payments and products for an invoice, you need to retain more information about your customer and product catalog, so you can easily charge for those products—whether it’s on a recurring basis or through a one-time invoice.

Here’s an overview of the core objects used to build and manage products and subscriptions:

Products

A Product on Stripe represents a physical product or service that you offer. You can create Products with either the Stripe Dashboard or the Products API:

Here’s an example creating a Product through the API:

curl https://api.stripe.com/v1/products \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "name"="Acme Premium Subscription"

Prices

Products can have multiple Prices. Those Prices define not only how much to charge and in which currency, but also how often. You can use them for recurring or one-time purchases, and they support various business structures from flat rate to per-seat, tiered and usage-based or metered billing. As with Products, you can manage them through the Dashboard or with the Prices API. If you use the API, you need to pass in the Product ID along with other pricing details:

Here’s an example creating a Price for fixed-price or per-seat Product through the API:

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "product"="{PRODUCT_ID}" \
  -d "unit_amount"=1000 \
  -d "currency"="usd" \
  -d "recurring[interval]"="month"

Aside from predefining and configuring Prices through the Dashboard and API, you can also create ad-hoc Prices when creating an Invoice or Subscription. You can pass in price_data instead of a Price ID for example, when subscribing a customer to a subscription.

Coupons

Coupons in Stripe provide discounts on recurring charges. Like subscriptions, coupons allow for great flexibility in how you define and use them. They can apply to every invoice or just for a certain length of time—to discount single items, against all items of an invoice, apply to every subscription a customer has, take off a percentage, reduce the amount by a flat amount, and so on. You can create coupons with the Dashboard or the API.

Here’s an example creating a Coupon that can be applied once (one cycle of a subscription) and takes 30% off:

curl https://api.stripe.com/v1/coupons \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "duration"="once" \
  -d "percent_off"=30

Tax Rates

To collect taxes and properly display tax amounts on an invoice, you can create and set tax rates on the Subscription, Invoice or invoice item. Stripe also calculates the total tax amount per tax rate and summarizes it in a table containing collected tax rates and amounts, that you can export from the Dashboard. Tax rates can be inclusive or exclusive and you can tie them to a jurisdiction to help with remittance.

Here’s an example API call that creates a Tax Rate object for California:

curl https://api.stripe.com/v1/tax_rates \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "display_name"="Sales Tax" \
  -d "description"="SF Sales Tax" \
  -d "jurisdiction"="CA - SF" \
  -d "percentage"=8.5 \
  -d "inclusive"=false

Customer objects: storing payment details

To store and reuse PaymentMethods, you must attach them to Customer objects.

After attaching the PaymentMethod to a Customer, store the Customer ID and PaymentMethod ID in your system to use it for payments in the future. Because one Customer object can have a list of multiple payment methods, you must specify both the Customer ID and the PaymentMethod ID when creating a charge later on.

Here’s an example creating a Customer and attaching a PaymentMethod:

curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "name"="Jenny Rosen" \
  -d "email"="jenny.rosen@stripe.com" \
  -d "payment_method"="{PAYMENT_METHOD_ID}"

Default payment methods for Customer objects

Because one Customer object can have a ​list of multiple payment methods, i​t’s important to mark one PaymentMethod as the default payment method for a Customer. We’ll use this default payment method for all future Invoices and Subscriptions if you don’t specify a different payment method.

Here’s an example setting the default payment method for a Customer:

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "invoice_settings[default_payment_method]"="{PAYMENT_METHOD_ID}"

Customer tax IDs for Customer objects

Displaying a customer’s tax ID on invoice documents is a common requirement. When using Stripe’s Invoice and Credit Note PDFs, the customer’s tax ID displays in the header of those documents. While you’re responsible for ensuring customer information is accurate (including their tax identification number), Stripe provides automatic validation to help determine if the formatting is correct, as well as automatic validation with government databases for certain tax ID types.

Here’s an example adding a tax ID for a Customer:

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/tax_ids \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "value"="DE123456789" \
  -d "type"="eu_vat"

Customer credit balances for Customer objects

Every customer in Stripe has a credit balance that you can issue credit and debit adjustments against. Adjustments in the credit balance could be a credit (meaning you owe them money, for example, from a Credit Note) or a debit (meaning they owe you money). These adjustments sum up to a balance on the Customer that you can apply to future invoices and subscriptions. Every credit to or debit from the customer balance leaves an audit trail that you can access using the Customer Balance Transactions API.

Here’s an example reading the transaction history for a Customer’s credit balance:

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/balance_transactions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Creating line items for invoices

Stripe supports the concept of Invoice Items which you can add as one-off items to a subscription or to start a one-off invoice. These are particularly useful for charging setup fees in addition to recurring payments, tracking individual components of a single payment, or augmenting a customer’s subscription in an arbitrary way.

Here’s an example adding an Invoice Item to the pending items for a Customer:

curl https://api.stripe.com/v1/invoiceitems \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "price"="{PRICE_ID}"

Creating a one-off invoice

After you create Invoice Items and they’re pending, you can create a one-off invoice to invoice immediately, or have a subscription pick those items up. In both cases, the resulting Invoice moves through a series of states from creation to getting paid. Stripe calls this process the automatic collection workflow. You can configure whether an Invoice should go through automatic collection by toggling the auto_advance property on the invoice.

Here’s an example creating an Invoice for the pending items of a Customer and finalizing it immediately:

curl https://api.stripe.com/v1/invoices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "auto_advance"=true

Customizing the invoice PDF

You can customize an invoice’s content and language to meet the needs of your business. This includes the language (taken from the Customer’s preferred_locales), the invoice numbering scheme and per-invoice customizations like additional, custom fields, a memo or addition to the footer. You can set the default content of the memo and footer in the Stripe Dashboard and override it by settings on the Customer (invoice_settings), the Subscription (if the invoice is created by a Subscription), and the Invoice itself (description, custom_fields and footer parameter).

Here’s an example modifying the custom fields, memo, and footer on an invoice:

curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "description"="This is the memo." \
  -d "custom_fields[0][name]"="PO Number" \
  -d "custom_fields[0][value]"=12345

Setting tax rates on invoices

Before finalizing the Invoice, you should determine whether you need to add taxes to your invoice (often dependent on local regulations and laws). Aside from the different rates, taxes can be exclusive or inclusive, and can apply to a single line item or the whole invoice. As soon as you have a Tax Rate object, you can use it on Invoices and Subscriptions. Every Invoice Item, Invoice, and Subscription can have up to 10 tax rates.

Here’s an example creating an Invoice Item with a special tax rate:

curl https://api.stripe.com/v1/invoiceitems \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "price"="{PRICE_ID}" \
  -d "tax_rates[]"="{TAX_RATE_ID}"

Here’s an example using a Tax Rate as default for an Invoice (applies to all Invoice Items except those that have their own Tax Rates):

curl https://api.stripe.com/v1/invoices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "default_tax_rates[]"="{TAX_RATE_ID}"

Applying coupons to invoices

Coupons in Stripe provide discounts on one-off or recurring charges. To apply a Coupon, use the discounts parameter on the Invoice or single Invoice Items:

Here’s an example creating an Invoice Item with a special Coupon:

curl https://api.stripe.com/v1/invoiceitems \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "price"="{PRICE_ID}" \
  -d "discounts[0][coupon]"="{COUPON_ID}"

Here’s an example using a Coupon on an Invoice:

curl https://api.stripe.com/v1/invoices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "discounts[0][coupon]"="{COUPON_ID}"

After you apply a coupon, it becomes a Discount object. These Discount objects track information about the application of a Coupon and are particularly important for Coupons that are valid for multiple months.

The order of Coupons can be important and Coupons on Invoice Items are always applied before the Coupons on the Invoice.

Finalizing and paying an invoice

Every Invoice gets created in the draft state. While an Invoice is in draft, you can still edit all of its parameters. When all the edits are in, finalize the Invoice, thereby moving it into the open state. When an Invoice is finalized, Stripe ensures that an invoice number is assigned, certain properties become immutable, and the payment is prepared.

Before finalizing, decide how the Invoice should be paid using the collection_method parameter. You can decide to send_invoice (using the Customer’s email address) or charge_automatically (using a Customer’s payment method). If you use send_invoice, provide the days_until_due parameter so that Stripe can mark an invoice as past due. When sending an invoice, Stripe emails the invoice to the customer with payment instructions.

Here’s an example finalizing an Invoice:

curl https://api.stripe.com/v1/invoices/{INVOICE_ID}/finalize \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

If you decide to send out the invoice, you can download and send the Invoice PDF, or send the link to the associated Hosted Invoice Page where the customer can pay the Invoice by entering their payment information.

If you decide to charge the Customer’s card on file, you can do so by manually triggering the payment of the invoice.

Here’s an example paying an Invoice with a customer’s default payment method:

curl https://api.stripe.com/v1/invoices/{INVOICE_ID}/pay \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

If for some reason the Invoice was created in error, you can void it. Similarly, if an Invoice becomes uncollectible, you can mark that as well.

Creating a recurring subscription

A Subscription ties a Product’s Price to a Customer, managing the recurring payment schedule and properties of billing cycles for a particular Customer. You’ll create Subscriptions using the Subscriptions API.

Here’s an example creating a Subscription with one Price/Product:

curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "items[0][price]"="{PRICE_ID}" \
  -d "items[0][quantity]"=1

Customers and subscriptions have a one-to-many relationship, and it’s possible for one Customer to have many active subscriptions (each with many possible prices).

Modifying a subscription

After you create a subscription, you might want to change the details for it. Examples include changing the billing cycle (switching from monthly payments to yearly ones) and upgrading or downgrading the subscription (changing the edition, from “basic” to “premium”; or changing the quantity, like the number of seats). Stripe supports changing existing subscriptions without having to cancel and recreate them.

When executing those changes you can also change other parameters of the subscription. Resetting the billing cycle anchor (the recurring date a subscription will be renewed) is one option. Additionally, you can decide whether you want to prorate previously paid and new amounts, allowing customers to only pay for the difference of the remaining time on their active subscription.

When changing the items of the existing Subscription, you will first need to find the ID of the existing Subscription Item to be able to modify it.

Here’s an example API call upgrading or downgrading an existing subscription and prorating the changes:

curl https://api.stripe.com/v1/subscriptions/{SUBSCRIPTION_ID} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "proration_behavior"="create_prorations" \
  -d "items[0][id]"="{SUBSCRIPTION_ITEM_ID}" \
  -d "items[0][price]"="{NEW_PRICE_ID}"

If you need more flexibility or have more complex subscription scenarios, like upgrading a subscription at the end of the current billing cycle instead of executing the change immediately, use Subscription Schedules.

Canceling or pausing a subscription

By default, Stripe creates evergreen subscriptions and billing continues until the subscription is canceled. One way to automatically term a subscription is to use the cancel_at or cancel_at_period_end parameter when creating or updating it. Alternatively, you can also cancel subscriptions yourself, either through the API or the Dashboard.

Here’s an example canceling a Subscription at the end of the current period (billing cycle):

curl https://api.stripe.com/v1/subscriptions/{SUBSCRIPTION_ID} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "cancel_at_period_end"=true

You can still reactivate a Subscription that wasn’t canceled yet but is set to cancel at a later date by unsetting the corresponding fields.

If you want to temporarily offer your products and services for free, you don’t need to cancel the subscription and can pause it instead. For invoices that would be created while the subscription is paused, you have to define their behavior, whether they should be marked as uncollectible, voided or kept as drafts for later collection.

Here’s an example pausing a Subscription and keeping new Invoices for a decision later:

curl https://api.stripe.com/v1/subscriptions/{SUBSCRIPTION_ID} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "pause_collection[behavior]"="keep_as_draft"

Multi-product subscriptions

If you offer multiple products that a customer can subscribe to, you might want to put them all into one Subscription to have Stripe invoice them together. To do so, you can specify multiple items when starting or modifying a Subscription. However, there are certain limitations: all of the Prices for those products must use the same currency, all must have the same billing interval (for example, all monthly), and you’re limited to 20 products in a single Subscription.

Here’s an example creating a Subscription with two Prices/Products:

curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "items[0][price]"="{PRICE_ID_PRODUCT_1}" \
  -d "items[1][price]"="{PRICE_ID_PRODUCT_2}"

Subscriptions: metered subscriptions

In some cases, you might have a product that doesn’t get paid with a fixed price or per-seat but is instead based on usage. Metered subscriptions allow you to charge your customer, for example, for the number of minutes or GB used per month at the end of each month. The invoicing model changes for this—while you charge for fixed-price and per-seat subscriptions upfront, you charge for metered subscriptions in arrears.

To create a metered subscription, you first need to create a metered Price:

Here’s an example creating a metered Price:

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "product"="{PRODUCT_ID}" \
  -d "currency"="usd" \
  -d "recurring[interval]"="month" \
  -d "recurring[usage_type]"="metered" \
  -d "unit_amount"=3000

Similar to fixed-price and per-seat Prices, the unit_amount specifies how much you charge per unit used (for example, per minute or GB). In certain cases, you might find that the smallest currency unit (for example, 0.01 USD) is still too large for the unit you picked. If that’s the case, you can use unit_amount_decimal instead of unit_amount and provide up to 12 decimal places for the currency of your choice.

While you might want to sum up the all usage at the end of the month, you can optionally provide the aggregate_usage parameter when creating a Price and specify last_during_period (the amount of the most recent usage record for the billing period will be used), last_ever (the amount of the most recent usage record ever provided), or max (the amount of the usage record with the largest usage quantity for the billing period).

After you have a metered Price, you can use it as usual when creating a Subscription. During each billing period, you then have to provide Usage Records, so Stripe can invoice and charge for the corresponding amount at the end of each billing period.

Here’s an example creating a Usage Record for a Subscription Item created from a metered Price:

curl https://api.stripe.com/v1/subscription_items/{SUB_ITEM_ID}/usage_records \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "quantity"=100 \
  -d "timestamp"=1610668800 \
  -d "items[0][price]"="{NEW_PRICE_ID}"

While your action for metered Prices that aggregate usage by sum is increment, you need to use action=set otherwise. Because it’s especially important that we don’t count usage for metered subscriptions multiple times, use Idempotency Keys when sending Usage Records (it’s generally a good idea to use them for all your requests).

Tiered subscriptions

Another type of subscription is tiered subscriptions. While the associated Prices are similar to per-seat Prices, tiered Prices don’t have a fixed unit_amount but instead change the amount per unit depending on the number of units. Here’s an example with three tiers: 1-10 units cost 5 USD per unit, 11-25 units cost 4 USD per unit, and >25 units cost 3 USD per unit (volume pricing). So, if you buy 15 units, you’ll pay 15 * 4 USD = 60 USD.

Here’s an example creating a tiered Price with three different tiers:

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "product"="{PRODUCT_ID}" \
  -d "currency"="usd" \
  -d "billing_scheme"="tiered" \
  -d "tiers_mode"="volume" \
  -d "recurring[interval]"="month" \
  -d "tiers[0][up_to]"=10 \
  -d "tiers[0][unit_amount]"=500 \
  -d "tiers[1][up_to]"=25 \
  -d "tiers[1][unit_amount]"=400 \
  -d "tiers[2][up_to]"="inf" \
  -d "tiers[2][unit_amount]"=300

Aside from a price per unit, every tier can also have a flat_amount. This amount is paid in addition to the unit costs but it’s only due once, not per unit.

Tiered pricing also has a second tiers_mode which is graduate. In that case, units are priced per tier meaning that, in the example above, the first 10 units would have a price of 5 USD (= 50 USD) and the remaining 5 units would have a price of 4 USD (= 20 USD), so the total would be 70 USD.

When using graduate tiers, the flat fee of each tier reached would also be charged (for example, in the example above, the flat fee for tier 1-10 and tier 11-25 would be charged).

Starting subscriptions with a trial

If you like to offer your customers a trial for your subscriptions, you can start subscriptions using the trial_end or trial_period_days parameter. While the former takes a timestamp indicating the exact moment the trial should end, the latter is the number of days the trial should last, from the current moment. When you create a Subscription with a trial, no PaymentMethod is required for the Customer.

Here’s an example starting a Subscription with a week-long trial:

curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{CUSTOMER_ID}" \
  -d "items[0][price]"="{PRICE_ID}" \
  -d "trial_period_days"=7

When creating a Subscription with a trial period, an invoice is still created but it will be for $0 and automatically marked as paid. When the trial period is over, another invoice will be issued and the Customer will be charged (unless it’s a metered subscription where the charges happen in arrears).

Applying coupons to subscriptions

Similar to one-off Invoices, Coupons can be added to Subscriptions and Subscription Items.

For Subscriptions, it’s particularly important to understand the difference between a Coupon and a Discount.

Just like with Invoice Items and Invoices, Coupons on Subscription Items will always be applied before Coupons on the Subscription.

Setting tax rates on subscriptions

Similar to one-off Invoices, Tax Rates can be added to Subscriptions and Subscription Items.

Refunds using credit notes

Refunds for Invoices–whether from subscriptions or one-off invoices–are managed using the ​Credit Notes​ API and might be made for full or ​partial​ amounts. Keep in mind that to refund parts of an invoice, you need the Stripe Invoice ID.

Refunds use your available Stripe balance, and can’t use your pending balance. If your available balance doesn’t have sufficient funds to cover the amount of the refund, Stripe debits the remaining amount from your bank account. You can create a Credit Note for partial refunds, full refunds, and more than one refund for an invoice, but you can’t refund a total greater than the original charge amount.

Credit Notes can be issued using the API or the Dashboard and are processed immediately. In general, there are two kinds of refunds that you can make through Credit Notes: refunds for existing line items (type=invoice_line_item) or refunds for custom amounts (type=custom_line_item).

When refunding an existing line item, you can refund it in full or credit back a certain number of units (which will calculate the correct amount based on the units price). For custom line items, you can freely choose the unit_amount and quantity to credit back, however the total amount cannot be greater than the total amount of the original invoice.

Here’s an example (partial) refund for two units of an existing line item:

curl https://api.stripe.com/v1/credit_notes \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "invoice"="{INVOICE_ID}" \
  -d "lines[0][type]"="invoice_line_item" \
  -d "lines[0][invoice_line_item]"="{INVOICE_ITEM_ID}" \
  -d "lines[0][quantity]"=2

Here’s an example (partial) refund for a custom amount (for example, courtesy credits):

curl https://api.stripe.com/v1/credit_notes \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "invoice"="{INVOICE_ID}" \
  -d "lines[0][type]"="invoice_line_item" \
  -d "lines[0][description]"="Courtesy credit" \
  -d "lines[0][quantity]"=1 \
  -d "lines[0][unit_amount]"=1000

Aside from the two types of line items, Credit Notes also give you three different ways to credit back the difference: credit the amount back to the Customer’s original PaymentMethod using refund_amount, credit to the Customer Credit Balance in Stripe using credit_amount (which will be automatically applied to future invoices), or credit outside of Stripe using out_of_band_amount. You can specify one or more of these parameters and split the total credit between them.

You can issue refunds using the API or the Dashboard. You can’t cancel a refund after you issue it. It will take 5 - 10 business days for the refund to appear on the customer’s statement. If a customer is curious about the status of their refund, you can provide the ARN so that they can inquire about the refund with their bank.

Disputes and chargebacks

Your business is responsible for managing disputes (also known as chargebacks). We recommend that you actively monitor disputes and collect and submit evidence to support the validity of charges where appropriate.

We hold disputed funds and deduct them from your Stripe balance pending a decision. We return the funds if you win the dispute.

You can monitor disputes in two ways:

• Use the Stripe Dashboard and email notifications that you can configure in your Dashboard profile.
• You can fully automate the dispute response and evidence submission through the Disputes API.

See the video guides on Fraud and dispute prevention and Responding to disputes for more.

You can use the Billing settings in the Dashboard to automatically cancel subscriptions that were disputed.

You can use webhooks to capture events that occur on your account (like payouts to your bank account, refunds, payments, etc). They’re helpful when handling Stripe events that occur asynchronously, or for those that you want to trigger additional actions for.

Additionally, there are a number of Billing-specific subscription events you should capture and take action on:

Stripe’s guide on webhooks for Billing provides additional insight on how to best leverage an event-driven architecture and webhooks for your integration.