Modeling pre-order and Try Before You Buy (TBYB) apps
This guide explains the lifecycle of a pre-order and TBYB app, high level tasks for building pre-order and TBYB options in your app, prohibited actions, and the division of responsibilities between Shopify and apps.
Lifecycle of a pre-order or TBYB app
Anchor link to section titled "Lifecycle of a pre-order or TBYB app"The following diagram illustrates the lifecycle of a pre-order or TBYB option based on the actions of a merchant, a customer, Shopify, and your app:
- The merchant creates a pre-order or TBYB option through the app and adds products and variants to the selling plan.
- The customer purchases products with the pre-order or TBYB option.
- Shopify creates an order, and then creates the payment term and the fulfillment for the order. Shopify also vaults the payment method.
- The customer can update their payment method in one of the following ways:
- Use an optional interface for managing orders that are created by the app.
- Ask the merchant to send them a payment email through the payment method component on the customer details page in the Shopify admin.
- The app is responsible for capturing the remaining balance amount.
- The app is responsible for updating Shopify's data with any fulfillment and payment term adjustments that are made in the app.
Building pre-order and TBYB option in your app
Anchor link to section titled "Building pre-order and TBYB option in your app"Building pre-order and TBYB options in your app includes the following tasks:
| Area | Task |
|---|---|
| Plan setup | Save selling plans You can use the SellingPlanGroup and SellingPlan objects to store selling plans and associate them with products or variants. Regardless of whether your app has an internal representation of selling plans, you need to save the selling plans in Shopify using the SellingPlanGroup and SellingPlan objects.Learn more about GraphQL Admin API objects for selling plans. |
| Set up app extensions Your app should provide the experience for users to manage their selling plans. The app should implement an embedded UX that enables the user to set up selling plans directly from the product page, using an app extension. If there aren't any app extensions to modify selling plans that are associated with a given product or variant, then the selling plans are listed in a read-only state on the product page in the Shopify admin. |
|
| Plan purchase and checkout | Display selling plans in the purchase flow Shopify provides Liquid objects and the Ajax API to enable theme developers to display the selling plans for a given product in the purchase flow. To purchase a product with a purchase option, a variant ID and a selling plan ID need to be submitted through the Cart API. Learn more about how to implement subscriptions in a theme. |
| Display selling plans in the checkout The Shopify checkout handles carts containing line items that have plans associated with them. It also handles pricing, messaging, payment method vaulting, and customer consent, which the user should customize to their needs. |
|
| Create subscription contracts The subscription contract describes the agreement between merchant and customer. The agreement includes key information, like the variant, plan, payment method to be used for subsequent billing, and the billing and shipping addresses. Shopify automatically creates subscription contracts when products with selling plans are purchased through checkout. The contract is detached from the original plan. Updating the original plan doesn't modify pre-existing subscription contracts. |
Requirements
Anchor link to section titled "Requirements"Pre-order and TBYB apps must meet the following requirements:
- The app must include an in-product mechanism to allow a merchant's customers to cancel or discontinue their pre-order or TBYB option.
- Apps that offer pre-orders must communicate to a merchant's customers when there's a delay in the stated shipment time.
- Apps that offer pre-orders obtain customer consent to delays that exceed 30 days if no shipping time is stated and include a mechanism to return the funds in case customer consent is not obtained.
Prohibited actions
Anchor link to section titled "Prohibited actions"The following are prohibited actions for all selling plans:
- Vaulting payment methods: Don't vault payment methods for any purpose other than processing recurring or deferred payments.
- Overbilling: A selling plan specifies how to bill a customer. Don't overbill a customer.
- Unsupported usage: APIs are built to support only authorized selling plans, such as pre-orders, try before you buys, and subscriptions. Don't use the APIs to solve for other business use cases, such as installments, layaways, and crowdfunding campaigns.
Division of responsibilities between Shopify and apps
Anchor link to section titled "Division of responsibilities between Shopify and apps"The division of responsibilities allows Shopify to provide a fully integrated experience and enables apps to provide innovative user-facing workflows and management automation.
The following table describes the division of responsibilities between Shopify and pre-order and TBYB apps.
| Responsibility | Shopify | App |
|---|---|---|
| Modeling and storing pre-order and TBYB business data | ✔ | |
| Collecting initial payments | ✔ | |
| Storing payment methods | ✔ | |
| Managing inventory | ✔ | |
| Labeling whether it's a pre-order or try before you buy | ✔ | |
| Handling trial and return periods for try before you buy purchases | ✔ | |
| Providing a customer interface for managing orders with deferred payments | ✔ | |
| Automating when to run a pre-order | ✔ | |
| Charging customers on the balance due date | ✔ | |
| Scheduling fulfillments | ✔ |
- Learn how to manage pre-order and TBYB options using the GraphQL Admin API.