Shop Component - Troubleshooting Guide

Note

NOTE: This document is only applicable to select merchants and partners using 3rd party checkout solutions. For more information, contact our enterprise sales team.

Anchor to OverviewOverview

This guide provides a method for troubleshooting a Shop Component implementation.

Anchor to Understanding Shop ComponentUnderstanding Shop Component

During checkout, your system is canonical for:
- Products & Inventory
- Shipping methods and rates
- Pickup locations and rates
- Discounts, rewards and promotions
- The cart
Shopify is canonical for:
- Customer addresses
- Payment information
  - Full details never given to merchant
  - Last 4 digits and brand of card returned on successful authorization, during the checkout process
- Transactions
Tracking & notifications:
- Once your system has updated the tracking information within Shopify, the Shop app will send push notifications to customers according to their preferences, and allow them to track their packages within the Shop app
- Your system is responsible for sending any order-related email notifications to customers
- Shopify will not send email notifications to customers for orders created through Shop Pay
Both Shopify and your existing e-commerce system will have records of any orders placed through Shop Pay
- The Shopify order allows you to manage the transaction (captures, voids, refunds, etc.) and fulfillment (providing tracking details which are essential for the Shop app experience) via Shopify’s APIs and/or the Shopify admin
- The order created in your e-commerce system is still required for your own purposes, such as inventory reservation, and coordination with your Order Management System (OMS).

Anchor to Shop Component WorkflowShop Component Workflow

The Shop Pay Checkout workflow can be divided into two major sections:

Pre-payment (checkout)

This includes everything from first exposure to Shop Pay, including everything until order creation
The session is created with the ShopPayPaymentRequestSessionCreate mutation via the Shopify Storefront API
The transaction is completed with the ShopPayPaymentRequestSessionSubmit mutation via the Shopify Storefront API
Information is passed between Shopify and your e-commerce platform via events in the frontend

Post-payment

This includes everything after order creation, and includes order management actions such as captures, refunds, and updates to fulfillment information
All actions taken after order creation are made through Shopify's Admin API

Anchor to Checkout OverviewCheckout Overview

Customer clicks the Shop Pay button or enters a recognized email
Customer authenticates with Shop
Your backend system builds the initial payment request using data for which it is the canonical source
Your backend system initializes the Shop Pay session via the Shopify Storefront API
The main Shop Pay user action loop:
- User takes a supported action within the Shop Pay popup:
  - Shipping address selection
  - Shipping type selection (Shipping vs Pickup)
  - Shipping method or pickup location selection
  - Entering or removing a discount code
  - Paying with a vaulted payment method
- Shop Pay popup emits the relevant event to your frontend, including the latest payment request details
- Your frontend makes a call to your backend system with the relevant information
- Your backend system validates the changes and determines the result of those changes
- Your backend system returns the details to the frontend in the call response
- Your frontend rebuilds the payment request as necessary, and passes it back to Shopify via the corresponding event completion call
Once “Pay now” is clicked, we include the encrypted payment_method token with the payment request passed to your frontend
Your backend system validates the payment request, then reserves inventory and optionally generates an order name, typically by creating an order in your ecommerce system
Your backend system submits the payment request via the Shopify Storefront API
If an authorization is not successful, the user can take additional actions within the Shop Pay popup, including attempting payment again
When the authorization is successful, Shopify creates the order asynchronously and sends the paymentcomplete event to your frontend
- Your system can also query the order by source_identifier, or receive the ORDERS_CREATE webhook to reconcile the order and confirm a successful authorization
It is crucial that your system responds to each event within 15 seconds by making the corresponding complete call to avoid a timeout. Additionally, ensure your system responds to each event just once. Your system should also be prepared to handle any event in any order until a successful payment is confirmed.

Anchor to Troubleshooting the Checkout ProcessTroubleshooting the Checkout Process

Your system will configure the Shop Pay session on the frontend, and there you’re able to specify a debug parameter which will enable verbose logging in the browser console.

window.ShopPay.PaymentRequest.configure({

shopId: 1,

clientId: "[REPLACE-ME]",

debug: true

})

Open the console to see the events being emitted from the Shop Pay Checkout popup, and the responses being returned by your frontend:

[Shop Pay Payment Request] Dispatching sessionrequested event

[Shop Pay Payment Request] Waiting on completeSessionRequest() callback

[Shop Pay Payment Request] Dispatching deliverymethodtypechanged event with: {deliveryMethodType: 'SHIPPING'}

[Shop Pay Payment Request] Waiting on completeDeliveryMethodTypeChange() callback

This console logging is useful to troubleshoot the flow of data between your system and the Shop Pay Checkout, as it will show you the payment request data from both the events originating from the Shop Pay Checkout popup, as well as the responses sent back to Shop Pay from your frontend.

Debug logging is intended for use in development environments only; remove it or set it to false in your production environment.

Anchor to Working with Shopify APIsWorking with Shopify APIs

Your developers will be integrating with Shopify’s Storefront API for the checkout process, as well as the Shopify Admin API for post-order actions such as captures, order reconciliation, and updating fulfillment/tracking information in Shopify. For more information on GraphQL, see About GraphQL.

Anchor to The Storefront APIThe Storefront API

During the checkout process, there are two Storefront API calls required to be made: ShopPayPaymentRequestSessionCreate when creating a Shop Pay session, and ShopPayPaymentRequestSessionSubmit for each attempted transaction. Note that these calls use different API endpoints and keys than those for post-order actions with Shopify’s Admin API.

Anchor to ShopPayPaymentRequestSessionCreateShopPayPaymentRequestSessionCreate

The most common issues with the ShopPayPaymentRequestSessionCreate mutation will stem from values not being correctly passed between the frontend and the backend servers, so the above troubleshooting steps for the checkout process are applicable. Assuming this is working as intended, and it’s the API call itself failing, Shopify should return an error message, so ensure that this is logged for any failure scenarios.

The ShopPayPaymentRequestSessionCreate can be safely retried, so automatic recovery should be possible if the first attempt fails for some reason.

Anchor to ShopPayPaymentRequestSessionSubmitShopPayPaymentRequestSessionSubmit

When processing payment attempts via ShopPayPaymentRequestSessionSubmit there are various errors that may surface related to validating the input. A few examples of why it might fail would be:

Not including any line items in the payment request
Not including any of the required parameters
Including negative values where positive values are expected in the payment request
Including objects within the payment request that aren’t a part of the ShopPayPaymentRequestInput
- The ShopPayPaymentRequestInput looks similar to, but is distinctly different than the payment request object that’s passed in the frontend
Similar to the ShopPayPaymentRequestSessionCreate mutation, it’s safe to retry the ShopPayPaymentRequestSessionSubmit mutation if necessary, however you must ensure that the payload, including the idempotency key, is exactly the same for retries stemming from a single payment attempt by the customer. This will ensure that if Shopify did already process the payment, then the resubmission by your system will not result in a duplicate payment.

Anchor to The Admin APIThe Admin API

The Admin API lets you build apps and integrations that extend and enhance the Shopify admin. While the Shop Component Storefront API mutations are only applicable to merchants with 3rd party e-commerce platforms, all Shopify merchants utilize the Admin APIs. Because of this, you may be able to find the answers to your questions by searching our developer forums.

For merchants using Shop Component, typically the Admin API functions will be handled by an Order Management System (OMS), however there are some functions which the e-commerce platform may want to leverage, such as webhook subscriptions, and querying orders for reconciliation purposes before handing an order off to the OMS.

Make sure the endpoint and API credentials for the Admin API are correct, as they differ from the Storefront API. Typically, separate Custom Apps are created for OMS systems or other integrations to ensure each uses dedicated credentials with appropriately scoped permissions.

Anchor to Shopify is AsynchronousShopify is Asynchronous

One of the most common challenges that developers face while working with Shopify, is understanding how and why Shopify performs certain tasks asynchronously. For Shop Component, this is relevant in a few ways:

Attempting payment by invoking the ShopPayPaymentRequestSessionSubmit mutation
- While the response returned by the API may indicate an immediate failure, a success indicates the successful enqueuing of the transaction, which is processed asynchronously
The paymentcomplete event will be emitted for successful authorizations (i.e. status: “SUCCESS”)
- As a client-side event, this event may not be received if a customer closes the popup early, or is otherwise disconnected from the session after initiating the payment
The ORDER_TRANSACTIONS_CREATE webhook triggers only when a payment is successfully authorized; however, any failed payment attempts by the customer during the Shop Pay session will also generate transactions and corresponding webhook events, which will be queued and delivered along with the successful payment event.
Order reconciliation:
- Once your e-commerce system has successfully reconciled the order and retrieved the Order ID, FulfillmentOrder ID and Transaction ID, then it’s typically ready for handoff to the OMS.
- Some aspects of an order are dynamic and could be updated after order creation, (ex. OrderRisks can be updated until the order is marked as fulfilled), so it’s important that any system concerned with the state of an order verifies it immediately before taking irrevocable actions, such as captures and fulfillments
Post-order actions:
- Transaction-related functions will normally require asynchronous processing, so the transaction status will often return as status: “PENDING”, and should get updated when processed
Webhooks:
- While normally delivered quickly, webhooks can in some cases be queued for some time before delivery, never depend on a webhook for time-sensitive critical path processes

Anchor to Inventory ReservationInventory Reservation

Because Shop Component transactions are finalized through Shopify Payments, it’s important for the inventory to be reserved and the order to be as certain as possible in your system, before submitting the ShopPayPaymentRequestSessionSubmit mutation. Once the payment is submitted and successful, the order is imported into Shop App for the buyer. This will trigger any relevant notifications to the Shop buyer (based on their notification preferences).

Your system should be equipped to handle multiple payment attempts during checkout, such as when a card is declined due to insufficient funds and the buyer uses a different card.

If a successful status is received, then the customer can be forwarded to the thank-you page as normal. If instead another action-driven event is received, then the cart should be rebuilt if necessary, before processing the action.

Anchor to Requesting development assistance from ShopifyRequesting development assistance from Shopify

While Shopify typically does not provide API troubleshooting assistance, we are happy to investigate issues encountered with the use of Shop Component. As a part of this, we provide launch services for merchants developing Shop Component integrations, and inquiries with our support are routed to teams equipped to assist.

Whenever requesting Shopify’s assistance on an investigation, it’s important to share the most recent example(s) you’re able to find, as Shopify will have access to the most detailed logging for more recent events.

Further, by providing any relevant API calls, their response and the headers from the responses, this will give Shopify the information needed to identify the relevant logs and help find a solution. Specifically, the X-Request-Id header is useful for identifying relevant logs when investigating issues.

If the issue is unrelated to an API call specifically, but rather related to missing orders, please provide the most relevant information about the order(s), such as the source identifier.