Modeling deferred purchase option apps
This guide explains the lifecycle of a deferred purchase option app, high level tasks for building deferred purchase options in your app, prohibited actions, and the division of responsibilities between Shopify and apps.
Lifecycle of a deferred purchase option
Anchor link to section titled "Lifecycle of a deferred purchase option"The following diagram illustrates the lifecycle of a purchase option based on the actions of a merchant, a customer, Shopify, and your app:
- The merchant creates a deferred purchase option through the app and adds products and variants to the deferred purchase option.
- The customer purchases products with the deferred purchase 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 deferred purchase options in your app
Anchor link to section titled "Building deferred purchase options in your app"Building deferred purchase options in your app includes the following tasks:
Enable merchants to set up and manage how they want products or variants to be sold.
SellingPlanGroup
and SellingPlan
Anchor link to section titled "SellingPlanGroup and SellingPlan"You can use the SellingPlanGroup
and SellingPlan
objects to store purchase options and associate them with products or variants. Regardless of whether your app has an internal representation of purchase options, you need to save the purchase options in Shopify using the SellingPlanGroup
and SellingPlan
objects.
Learn more about GraphQL Admin API objects for purchase options.
Using app extensions
Anchor link to section titled "Using app extensions"Your app provides the user experience to merchants to manage their purchase options. The app should implement an embedded UX that enables the merchant to set up purchase options directly from the product page, using an app extension.
If there aren't any app extensions to modify purchase options that are associated with a given product or variant, then the purchase options are listed in a read-only state on the product page in the Shopify admin.
Plan purchase and checkout
Anchor link to section titled "Plan purchase and checkout"Display purchase options to customers in the purchase flow.
Liquid drops and the Ajax API
Anchor link to section titled "Liquid drops and the Ajax API"Shopify provides Liquid drops and the Ajax API to enable theme developers to display the purchase options for a given product in the purchase flow.
To purchase a product with a purchase option, a variant ID and a SellingPlan
ID need to be submitted through the Cart API.
To learn more about how to implement purchase options in a theme, refer to Purchase options.
Checkout and customer-facing UX
Anchor link to section titled "Checkout and customer-facing UX"Checkout handles carts containing line items that have plans associated with them. It also handles pricing, messaging, and payment method vaulting and customer consent, which the merchant should customize to their needs.
Requirements
Anchor link to section titled "Requirements"Deferred purchase option apps must meet the following requirements:
- The purchase option app must include an in-product mechanism to allow a merchant's customers to cancel or discontinue their purchase 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 purchase options:
- Vaulting payment methods: Don't vault payment methods for any purpose other than processing recurring or deferred payments.
- Overbilling: A purchase option specifies how to bill a customer. Don't overbill a customer.
- Unsupported usage: APIs are built to support only authorized purchase options, 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 purchase option experience and enables apps to provide innovative user-facing workflows and purchase option management automation.
The following table describes the division of responsibilities between Shopify and deferred purchase option apps.
Responsibility | Shopify | App |
---|---|---|
Modeling and storing purchase option business data | ✔ | |
Collecting initial payments | ✔ | |
Storing payment methods | ✔ | |
Managing inventory | ✔ | |
Labeling whether the purchase option is 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 | ✔ |