The Orders API is a subset of the Stripe API consisting of the following objects:

Product, a blanket representation of an item your business sells (for instance, “2015 Limited Edition T-shirt”).
SKU (Stock Keeping Unit), a specific product variation, taking into account any combination of attributes and cost (for instance, size, color, currency, cost).
Order, a combination of customer information and the SKUs they want to purchase.

Stripe lets you manage pricing and inventory, automatically calculate shipping costs and taxes, and create and pay for orders. To get started with orders, you should define products and SKUs and configure shipping and tax integrations. Once your inventory is set up, you can create and pay for orders.

The end of this guide presents best practices and explains how to use webhooks. Although all of this functionality can be implemented using the Dashboard alone, this guide focuses on developer usage of the Orders API. Developers can also read the Orders Guide for additional information, including best practices.

When to use orders

Orders integrate nicely with other parts of the Stripe API that you might already be familiar with. For example, paying an order creates a charge object. Similarly, returning an order will create a refund for all or part of that charge. Orders support additional features beyond basic charges that you might find helpful:

Calculate taxes due on orders via Avalara or TaxJar
Retrieve shipping rates from USPS, FedEx, and more using EasyPost or Shippo
Keep track of fulfilled orders and seamlessly handle returns
Import products from a Google or LinkShare product feed

Using the Orders API would be a good idea if any of the following apply to you:

You need to calculate taxes or shipping for the products you are selling
You sell physical goods than can be shipped and returned by customers
You want to sell your products on Twitter, ShopStyle, or other applications via Relay

On the other hand, there are some cases where other Stripe products would be easier to use:

If you want to charge customers on a recurring basis, subscriptions let you do that easily
If you are selling a variable-rate service (like a Lyft ride), charges give you more flexibility
If you already have an inventory, tax, and shipping system, you may not need the extra features that Stripe orders provide

Define products and SKUs

Begin by using the API or the Dashboard to represent your product catalog as Product and SKU objects. Product is an umbrella for the types of goods you sell, be they physical–to be shipped–or digital–to be downloaded. (See the best practices for examples and additional tips.)

Products can have associated images, descriptions, and more. The attributes property is how a product defines the features that can be set on individual SKUs: the specific versions of the product a customer actually buys. For example, the above code says that the “2015 Limited Edition T-shirt” product comes in different variations for size, gender, and color.

With a product defined, create specific product variations as SKUs, taking into account all possible combinations of attributes.

The above code creates two different SKUs–variants on a product, differentiated by size and price. You will normally have exponentially more SKUs than products. If the “2015 Limited Edition T-shirt” came in three sizes–small, medium, and large–and in two colors–cyan and magenta, there would be at least 6 SKUs representing it.

Configure shipping and tax handling

Real-world orders involve not only the cost of the items being purchased, but also shipping costs and taxes. Stripe can automatically and dynamically add these costs to your orders.

Configure your shipping and tax preferences in your Stripe account, by choosing one of three approaches.

Shipping can be set as:

provider: A third-party provider like EasyPost or Shippo which will provide the shipping rates dynamically
flat_rate: One or more fixed-cost options like Standard, Express, and Overnight shipping. You can even opt to waive the shipping cost above a certain order total.
free: No additional cost, the default

Tax can be set as:

provider: A third-party provider like Avalara or TaxJar which will provide the tax amount dynamically
percentage: A flat additional cost, as a percent of the order total, before shipping
included: No additional cost, the default

Both shipping and taxes can also be set to callback. If you wish to calculate shipping and taxes yourself, provide an endpoint on your own server that Stripe will reach out to in real-time to retrieve these costs. This can be helpful if you want to use the Orders API but have an existing system for shipping and taxes or if you want to sell through an application like Twitter via Relay.

Create and pay for orders

With your products and SKUs already on Stripe, it is time to start creating orders. When using orders, your checkout flow will most likely look something like the following:

A customer picks one or more items (SKUs) that they want to purchase
You create an order containing those items to retrieve tax and shipping costs from Stripe
The customer provides you with payment credentials that you use to pay the order

We will focus on the two last steps here. To create an order, specify the SKUs in the order as well as the customer’s shipping address:

You will receive an order object in the response (some fields omitted for brevity):

        {
  "id": "or_18Q3IaDAu10Yox5RqlL8JnnS",
  "amount": 8239,
  "status": "created",
  "items": [
    {
      "type": "sku",
      "amount": 6999,
      "description": "Slim Jeans",
      "parent": "sku_8XOBjVaulB0SWy",
      ...
    },
    {
      "type": "tax",
      "amount": 525,
      "description": "CA STATE TAX (P0000000)",
      "parent": null,
      ...
    },
    {
      "type": "shipping",
      "amount": 560,
      "description": "USPS Priority Mail",
      "parent": "ad989a994218446fbd48978a6ac905b0",
      ...
    }
  ],
  "selected_shipping_method": "0083dfe889534b75bf8ca73aa703e938",
  "shipping_methods": [
    {
      "id": "ad989a994218446fbd48978a6ac905b0",
      "amount": 560,
      "description": "USPS Priority Mail",
      ...
    },
    {
      "id": "db18a419e6f14aba82aa41f2bb9ec08e",
      "amount": 595,
      "description": "USPS Parcel Select",
      ...
    }
  ],
  ..
}
      

To create this order, Stripe automatically did several things for you:

Verified that the SKU was still in stock and retrieved its current price
Retrieved the taxes due from your tax provider and added a $5.25 tax line item
Retrieved shipping rates from your shipping provider and added the available shipping methods
Summed up all the line items and packed them into the order object

You should store the order id in your database and present the customer with the order total of $82.39. When your customer is ready to pay, you can collect their payment details. Then, simply pass the token to Stripe to pay the order:

Next up

Congrats! You’ve gone through how to use the APIs for products, SKUs and orders. Some things you might want to see next: