Create a customer-facing purchase option portal

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

• 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: https://my-purchase-option-app.com/app_proxy

Your app requires the following access scopes:

• write_products
• read_customer_payment_methods
• read_own_subscription_contracts
• write_own_subscription_contracts

• write_products
• read_all_orders
• read_customer_payment_methods
• read_purchase_options
• write_purchase_options
• read_payment_mandate
• write_payment_mandate

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,

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.

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 https://example.com/apps/my-purchase-option-app/.

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 subscriptionContractCreate mutation.

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:

Request: POST /admin/api/2024-04.json

JSON response:

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.

Request: POST /admin/api/2024-04.json

JSON response: