Create a customer-facing purchase option portal
This tutorial describes how to create an automated, secure purchase option portal where customers can manage their purchase option information without interacting with merchants. Customers can use an email link or button to access the portal.
What you'll learnAnchor link to section titled "What you'll learn"
In this tutorial, you'll learn how to do the following tasks:
- Expose a link or button to send an email
- Authenticate and access the customer-facing portal
- Make requests to the GraphQL Admin API to implement relevant views and forms on your app
- Update a customer's payment method
RequirementsAnchor link to section titled "Requirements"
- Create a subscription or deferred purchase option app.
Set up an app proxy with the following app proxy configuration:
- Subpath prefix: apps
- Subpath: my-purchase-option-app
- Proxy URL:
Access scopesAnchor link to section titled "Access scopes"
Your app requires the following access scopes:
SubscriptionsAnchor link to section titled "Subscriptions"
Deferred purchase optionsAnchor link to section titled "Deferred purchase options"
Step 1: Expose a link or button to send an emailAnchor link to section titled "Step 1: Expose a link or button to send an email"
Provide a link or button that triggers an email to be sent to a customer. You should place a link or button in an area that’s accessible to the customer.
You can provide a link or button in one of the following areas:
- On the customer account page on the storefront
- On the order status page, by customizing the order status page to expose a link or button
In an email, sent directly to the customer after the app receives an order creation webhook or a subscription contract creation webhook. The email should contain a secure login link for the customer. For example,
Step 2: Authenticate and access the customer-facing portalAnchor link to section titled "Step 2: Authenticate and access the customer-facing portal"
After you've exposed an action to send an email, the customer can use an email link to access the secure purchase option portal. Use an authentication scheme of your choice.
Step 3: Make requests to the GraphQL Admin APIAnchor link to section titled "Step 3: Make requests to the GraphQL Admin API"
After clicking the link, the customer is redirected to an endpoint predetermined by the URL.
For example, if the following URL is provided:
Then Shopify makes a request to the following endpoint:
The app can then implement the relevant views and forms. For example, the app might do the following implementation tasks:
- Updating billing and shipping addresses
- Pausing, unpausing, skipping, and canceling subscriptions
- Canceling and modifying pre-orders
All endpoints are forwarded from the app proxy into your app, as long as the links and form actions start with
When your app receives the request, you can make further requests to the GraphQL Admin API. For example, you can use the
sellingPlanCreate mutation and the
Step 4: Update a customer's payment methodAnchor link to section titled "Step 4: Update a customer's payment method"
For security reasons, customer payment methods, such as credit cards, can't be updated using the API. Customers need to authenticate their payment method where applicable or request a second email that redirects them to a secure flow where their payment method can be safely updated.
After a customer has updated their payment method, the information is available to the app using the same customer payment method ID.
The following request returns a secure URL to send to the customer to update their payment method:
If the response is an error message or if the customer needs to update their payment method at a later date, then you can use the customerPaymentMethodSendUpdateEmail mutation to send an email to the email address associated with the specified ID.