---
title: Shop Pay Component API
description: Add Shop Pay checkout to your existing ecommerce site using the Shop Pay Component API.
api_name: commerce-components
source_url:
  html: https://shopify.dev/docs/api/commerce-components/pay/index
  md: https://shopify.dev/docs/api/commerce-components/pay/index.md
---

# Shop Pay Component API

**Note:**

This API is **only available to select merchants and partners** using third-party checkout solutions. For more information, contact [our enterprise sales team](https://www.shopify.com/solutions/shop-pay/enterprise#contact-sales).

***

## Overview

The Shop Pay Component JS API enables your existing ecommerce site to use Shop Pay for checkout. Customers who select a Pay with Shop button or are recognized by email are shown all relevant cart information and can complete the transaction in an experience consistent with other usages of Shop Pay using a popup on your site.

### Glossary

| **Term** | **Definition** |
| - | - |
| Shop Pay login | Logging in to a Shop Pay account. This occurs directly between a customer and Shopify. |
| Payment request | A payment request includes line items, applied discounts, tax calculations and available shipping methods. |
| Authentication modal | When a Shop Pay user's email is recognized, the customer will see an interface to enter a One Time Password (OTP) for authentication. |
| Shop Pay popup | Most of the interactions in Shop Pay Checkout happen within the context of a Shopify-hosted popup window. |

### Technical requirements

* A Shopify account with Shopify Payments enabled
* The public domain(s) for the site you will be integrating Shop Pay Component into
* A non-Shopify-hosted ecommerce environment to implement against (frontend + backend)
* The content security policy on the frontend must be configured to allow `cdn.shopifycloud.com`, `cdn.shopify.com`, `shop.app`, `pay.shopify.com`, `*.shopifysvc.com`, `*.stripe.com`
* The backend needs to be able to functionally access all applicable resources required to assess and update the state of the payment request, including cart details, tax calculations, shipping methods / pricing, local pickup locations, discounts, inventory availability, etc.
* An understanding of the work necessary to integrate with the Order Management System and other backend systems to perform post-order actions in Shopify such as captures, refunds, and updating fulfillment information.

### Core Concepts

#### Your system is the main source of truth

This API extends your existing systems, so it treats those systems as canonical for everything that they already handle. This includes:

* Cart contents

* Shipping methods

* Pickup locations

* Tax calculation

* Discounts

* Inventory reservations

  Shopify is the source of truth for the payment transaction and for Shop Pay related fields, including vaulted customer addresses and payment methods.

  Consequently, while this API receives detailed information about the cart in the form of a payment request, any changes to the payment request related to your system's canonical topics must be validated. Whenever the payment request is returned to Shopify, it's used as a replacement for prior data received.

#### Shopify's order ID

Upon payment completion, the order ID is returned from Shopify via a webhook for use in post-order actions such as capturing payments, issuing refunds, and adding order tracking information.

#### Source identifier

Your system is responsible for providing a source identifier that uniquely identifies the order, and is often either an existing cart or order identifier from your system. This value is persisted onto the Shopify order record.

#### Shop Pay popup interactions

Shop Pay customers will authenticate with a Shop Pay login, either through an authentication modal or directly within the Shop Pay popup.

In order for Shopify to receive your system's canonical information during the checkout process, Shopify will dispatch events to your frontend integration when there are relevant customer actions in the Shop Pay popup. Following this, your system will then determine if there are any subsequent updates required to be made to the payment request. Based on its new state, calculate and rebuild an updated payment request to provide in the required response to the event.

Once accepted by a customer through the action of clicking the *Pay now* button, your backend should submit the [final payment request mutation](https://shopify.dev/docs/api/storefront/2024-07/mutations/shopPayPaymentRequestSessionSubmit), including the `paymentMethod` token provided by Shopify, resulting in processing the payment and order creation.

While the Shop Pay popup is open, an overlay will darken the background, however the cart on your shop may remain visible. It's important that a customer does not see a different total in the cart because it hasn't updated based on selected shipping methods or discounts applied in Shop Pay. To handle this, we recommend updating any cart totals while the user interacts with the Shop Pay Checkout so that values match. A potential fallback is displaying the totals in a pending state through microcopy like `Calculating...` or through skeletons, spinners, or other pending UI elements.

#### Order creation

A payment request must first be validated in your system including verifying that the payment request hasn't been modified unexpectedly, confirming inventory reservation, discount and pricing validation before submitting the final Shop Pay payment request, which will then create the order in Shopify.

Although rare, there can be a delay before an order becomes available via the Shopify API. It's important to ensure that synchronous order creation is not required for functionality of your checkout. Instead, webhooks can be relied upon for order creation confirmation.

***

## Sequence Diagram

This diagram reflects a "happy path" checkout. For simplicity, it bypasses the Shop Pay login flow, assuming a customer is already logged into Shop Pay.

![Shop Pay Component flow](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/api/commerce-components/pay/shop-pay-ccs-flow-DNhXgbRN.png)

***

## Reference

[JavaScript SDK\
\
](https://shopify.dev/docs/api/commerce-components/pay/javascript-sdk)

[Load the Shop Pay button and login web components into your site.](https://shopify.dev/docs/api/commerce-components/pay/javascript-sdk)

[Sessions and events\
\
](https://shopify.dev/docs/api/commerce-components/pay/sessions-and-events)

[Create payment request sessions and handle checkout events.](https://shopify.dev/docs/api/commerce-components/pay/sessions-and-events)

[Frontend API reference\
\
](https://shopify.dev/docs/api/commerce-components/pay/frontend-api-reference)

[Types, interfaces, and events for the frontend JavaScript SDK.](https://shopify.dev/docs/api/commerce-components/pay/frontend-api-reference)

[GraphQL pre-payment\
\
](https://shopify.dev/docs/api/commerce-components/pay/graphql-pre-payment)

[Create and submit payment request sessions using the Storefront API.](https://shopify.dev/docs/api/commerce-components/pay/graphql-pre-payment)

[GraphQL post-payment\
\
](https://shopify.dev/docs/api/commerce-components/pay/graphql-post-payment)

[Manage captures, fulfillment, refunds, and cancellations using the GraphQL Admin API.](https://shopify.dev/docs/api/commerce-components/pay/graphql-post-payment)

[Localization\
\
](https://shopify.dev/docs/api/commerce-components/pay/localization)

[Configure locale settings for multiple language support.](https://shopify.dev/docs/api/commerce-components/pay/localization)

[Monitoring and resiliency\
\
](https://shopify.dev/docs/api/commerce-components/pay/monitoring)

[Set up webhooks, handle disputes, and implement reconciliation.](https://shopify.dev/docs/api/commerce-components/pay/monitoring)

***

## Guides

[Development Journey and Key Considerations\
\
](https://shopify.dev/docs/api/commerce-components/pay/development-journey)

[A guide to assist with the development journey and key considerations for Shop Pay Component.](https://shopify.dev/docs/api/commerce-components/pay/development-journey)

[UX Guidelines\
\
](https://shopify.dev/docs/api/commerce-components/pay/design-guidelines)

[UX documentation for Shop Pay Component.](https://shopify.dev/docs/api/commerce-components/pay/design-guidelines)

[Shop Configuration Guide\
\
](https://shopify.dev/docs/api/commerce-components/pay/shop-configuration)

[New shop configuration guide for Shop Pay Component.](https://shopify.dev/docs/api/commerce-components/pay/shop-configuration)

[Troubleshooting Guide\
\
](https://shopify.dev/docs/api/commerce-components/pay/troubleshooting-guide)

[A guide to assist with troubleshooting Shop Pay Component implementations.](https://shopify.dev/docs/api/commerce-components/pay/troubleshooting-guide)

[Merchant-Assigned A/B Testing Guide\
\
](https://shopify.dev/docs/api/commerce-components/pay/merchant-assigned-ab-testing-guide)

[A guide to assist with performing A/B testing for Shop Pay Component.](https://shopify.dev/docs/api/commerce-components/pay/merchant-assigned-ab-testing-guide)

[Shop Pay Installments activation\
\
](https://help.shopify.com/en/manual/payments/shop-pay-installments/activating-shop-pay-installments)

[A guide to activating Shop Pay Installments.](https://help.shopify.com/en/manual/payments/shop-pay-installments/activating-shop-pay-installments)

***