Relay API Overview

Expand your commercial reach by selling your products directly within your customers’ favorite apps. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

The Relay 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, USD, $20.00).
  • Order, a combination of customer information and the SKUs they want to purchase.

Stripe automatically handles inventory changes, factors in shipping costs and taxes, and notifies you of activity via webhooks. To get started with Relay, you should define products and SKUs and set shipping and tax handling strategies.

The end of this guide presents best practices, explains how to use webhooks, and details the order lifecycle. Although almost all of this functionality–except for webhooks–can be implemented using the Dashboard alone, this guide focuses on developer usage of the Relay API.

The Relay API also lets Stripe users sell products across an expansive and expanding network of popular media. Customers can buy your goods through tweets, social media posts, in-app interfaces, ads, or even simple links.

Just add products to your Stripe account and connect to any number of apps–social media platforms like Twitter or mobile shopping apps like ShopStyle. The app can be used to promote your products, will handle the ordering process, and even securely accept payment on your behalf. Once an order is created and paid for, you simply fulfill the order to complete the transaction. You can start selling on third-party applications by connecting to Relay apps. This guide also outlines how to manage orders from Relay applications.

To learn more about building an app on the Relay API that other Stripe users can sell their products through, see the apps guide or the recipe for using the Relay Demo account.

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.

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

  • free: No additional cost, the default.
  • flat_rate: A flat additional cost, regardless of the items ordered, the quantity, or the customer’s geographic location. You can even opt to waive the shipping cost above a certain order total.

Tax can be set as:

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

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.

Best practices

To make the most of Relay, it’ll help to understand where the various objects and attributes come into play.

Defining products and SKUs

The first decision to make in organizing a catalog is to identify your products and SKUs. This can be tricky to grasp, but is important to get right.

Working backwards, a SKU is an individual product: the specific item the customer is actually buying. Anything you’d put into a shopping cart–real or online–is represented by a SKU.

Each product is an umbrella term for a family of SKUs. These should still be identifying, not too generic. “Book”, “coat”, “software”, and “coffee” are all too broad as products. Instead, you’d have:

  • A specific book title as a product, with formats–hardcover, softcover–and translations differentiated as SKUs.
  • An identifiable label and style of coat as a product, with sizes and colors defined as SKUs.
  • A named application as a product, with operating system versions and releases as SKUs.
  • A line of coffee–such as Jamaican Blue Mountain– as a product, with sizes, roasts, and ground establishing SKUs.

As a rule of thumb, customers would be unlikely to purchase two different SKUs from the same product family at the same time (unless they really wanted, for example, the same coat in two different colors).

Detailing products details for customers

Your goal is to provide as much useful, appealing information as you can about your products and SKUs. We recommend you do the following to take full advantage of the Relay API, especially if you plan on selling through Relay apps:

  • Use clear, descriptive names
  • Provide at least one product image
  • Use a dedicated web page, linked through the url field, to provide more detailed and alternative information (e.g., a video demonstrating the product)

Using webhooks

Receive real-time updates on the state of your products, SKUs, and orders using webhooks. The applicable Relay API events are:

  • product.created
  • product.updated
  • sku.created
  • sku.updated: e.g., inventory is decreased after a successful order
  • order.created
  • order.updated: the details of an order (e.g., shipping information) are updated
  • order.payment_succeeded: payment is made on an order
  • order.payment_failed: the payment attempt did not work

Your webhook endpoint can take specific actions when these events occur. You can expect to receive an order.created event whenever someone has begun the checkout flow for one of your products. An order.payment_succeeded event represents a purchase. In other words, once you have received an order.payment_succeeded webhook, it’s time to fulfill whatever product has been purchased.

Understanding the order lifecycle

When examining the response of any API call or webhook notification, use the Order object’s status attribute to verify the current status of the order and respond accordingly.

  • When an order is first requested, the resulting order object has an initial status of created.
  • When an order is paid, status changes to paid. You should now fulfill the order.
  • After fulfilling the order, update the Order object to change status to fulfilled. Only orders in the paid state can be marked as fulfilled.
  • If the customer cancels the order (through your site) before it’s been fulfilled, refund the associated payment and then update status to canceled.
  • If the order has been fulfilled and the customer returns the purchased items, refund the associated payment and then update status to returned.

Put another way:

  • A created order can become paid or canceled.
  • A paid order can become fulfilled or canceled. If the order becomes canceled, Stripe will automatically refund the payment.
  • A fulfilled order is normally the final state, but can be returned in which case the payment is refunded.

Connect to apps

Once you’ve defined products and SKUs in your Stripe account, you’re ready to connect your account to apps: popular shopping and social media platforms. By doing so, you enable users of those applications to buy your products without even visiting your website, greatly expanding your business’s reach. Apps can easily sell your products through every interface they offer, including mobile sites and apps. You can use the apps to promote your products, and then apps will take over: creating the orders and accepting payment on your behalf.

You’ll find some common apps to connect to listed in the Dashboard.

For apps not listed in the Dashboard, visit the respective app’s site to see if they offer a Stripe Relay integration. If so, they’ll provide a page that likely contains a button like:

Connect with Stripe

Just click on the button and follow through the interface to connect your account.

Note that you only need to register your products and SKUs in your Stripe account once, and you can connect to as many apps as you’d like. Just select the right platforms for your business, and Stripe takes care of sending them the right info to display your products in their app.

Stripe does allow apps to take an application fee on order payments. You may want to check an app’s policy on this before connecting.

Manage orders from Relay apps

When a customer buys products through an app you’ve enabled, the app will:

  • Create an order. This happens when the customer first establishes intent to purchase the product, such as by clicking a “Buy Button”.
  • Accept payment for the order. This happens at the end of the checkout flow.

With the order paid for, it’s time for you to fulfill it, whether that means providing a downloadable digital good or shipping a physical one.

Stripe will notify you of orders via email or webhooks. With webhooks, you’ll want to pay particular attention to order.payment_succeeded events, as they indicate further action is required on your part. With your own Relay integration, a developer would likely build a display of order information in a portal on your site for easy viewing.

If you’re relying upon email, use the Dashboard to obtain any further necessary information. On a specific order page, you can find the customer and order details.

Once you’ve delivered the order, mark it as fulfilled in your Stripe account. You can do this on the order’s page in the Dashboard, or by making an update order API call.

Understand that enabling a Relay application means giving it the ability to create and pay for orders with your products and SKUs. You can still use the API or the Dashboard to manage these orders including marking them as fulfilled, issuing refunds, etc.

Next up

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