Frontend API reference

Anchor to [object Object]`ShopPayPaymentRequestSession`

Shopify emits these events as the user interacts with Shop Pay. Listen for the events, and respond accordingly. For examples of attaching event listeners, refer to the sessions and events documentation.

The following interface defines the events and completion methods available on a ShopPayPaymentRequestSession:

interface ShopPayPaymentRequestSession {

// Requires a server call

sessionrequested: EventHandler<ShopPaySessionRequestedEvent>;

completeSessionRequest(sessionRequestResponse: {token, checkoutUrl, sourceIdentifier} & ShopPayPaymentRequestUpdate): void;

// Dispatched as the user changes various fields

deliverymethodtypechanged: EventHandler<DeliveryMethodTypeChangedEvent>;

completeDeliveryMethodTypeChange(update: ShopPayPaymentRequestUpdate): void;

pickuplocationchanged: EventHandler<PickupLocationChangedEvent>;

completePickupLocationChange(update: ShopPayPaymentRequestUpdate);

pickuplocationfilterchanged: EventHandler<PickupLocationFilterChangedEvent>;

completePickupLocationFilterChange(update: ShopPayPaymentRequestUpdate);

shippingaddresschanged: EventHandler<ShopPayShippingAddressChangedEvent>;

completeShippingAddressChange(update: ShopPayPaymentRequestUpdate): void;

deliverymethodchanged: EventHandler<ShopPayDeliveryMethodChangedEvent>;

completeDeliveryMethodChange(update: ShopPayPaymentRequestUpdate): void;

discountcodechanged: EventHandler<ShopPayDiscountCodeChangedEvent>;

completeDiscountCodeChange(update: ShopPayPaymentRequestUpdate): void;

// Dispatched once a customer clicks the Pay button in order to confirm

// the payment should be processed

paymentconfirmationrequested: EventHandler<ShopPayPaymentConfirmationRequestedEvent>;

completePaymentConfirmationRequest(update: ShopPayPaymentRequestUpdate): void;

// Dispatched after a payment processing attempt

paymentcomplete: EventHandler<ShopPayPaymentCompleteEvent>;

// Dispatched when a payment attempt has failed

paymentattemptfailed: EventHandler<ShopPayPaymentAttemptFailedEvent>;

// Dispatched after the checkout window is closed

windowclosed: EventHandler<WindowClosedEvent>;

// Cancels the session

close(): void;

}

interface ShopPayPaymentRequestUpdate {

updatedPaymentRequest?: ShopPayPaymentRequest;

errors?: ShopPayUserError[];

}

Field name	Type	Description
`sessionrequested`	Event handler	This event handler is triggered when a new Shop Pay session is requested. The listener must make a server-to-server call from your backend to Shop Pay's servers, and then call `completeSessionRequest()` from your frontend with the response.
`completeSessionRequest`	`(args: {token: string, checkoutUrl: string, sourceIdentifier: string} & ShopPayPaymentRequestUpdate) => void`	This function completes the session request. It must be invoked with the `token`, `checkoutUrl`, and `sourceIdentifier` from response of the `ShopPayPaymentRequestSessionCreate` mutation. You can optionally include an updated payment request.
`deliverymethodtypechanged`	Event handler	This event handler is triggered when a customer changes their preferred delivery method. When this event is triggered, `completeDeliveryMethodTypeChange()` must be called with the updated payment request.
`completeDeliveryMethodTypeChange`	`(args: ShopPayPaymentRequestUpdate) => void`	This function must be called when the delivery method type changes.
`pickuplocationchanged`	Event handler	This event handler is triggered when a customer changes the selected pickup location. `completePickupLocationChange()` must be called with the updated payment request.
`completePickupLocationChange`	`(args: ShopPayPaymentRequestUpdate) => void)`	This function must be called when the selected pickup location changes.
`pickuplocationfilterchanged`	Event handler	This event handler is triggered when the pickup location filter changes. `completePickupLocationFilterChange()` must be called with an updated payment request containing a filtered set of pickup locations.
`completePickupLocationFilterChange`	`(args: ShopPayPaymentRequestUpdate) => void`	This function must be called when the pickup location filter changes.
`shippingaddresschanged`	Event handler	This event handler is triggered when a customer changes their preferred shipping address. When this event is triggered, `completeShippingAddressChange()` must be called with the updated payment request.
`completeShippingAddressChange`	`(args: ShopPayPaymentRequestUpdate) => void`	This function must be called when the shipping address changes.
`deliverymethodchanged`	Event handler	This event handler is triggered when a customer changes their preferred delivery method. When this event is triggered, `completeDeliveryMethodChange()` must be called with the updated payment request.
`completeDeliveryMethodChange`	`(args: ShopPayPaymentRequestUpdate) => void`	This function must be called with the updated payment request.
`discountcodechanged`	Event handler	This event handler is triggered when the discount code changes. When this event is triggered, `completeDiscountCodeChange()` must be called with the updated payment request.
`completeDiscountCodeChange`	`(args: ShopPayPaymentRequestUpdate) => void`	This function updates the payment request after discount codes are changed by providing an updated payment request.
`paymentconfirmationrequested`	Event handler	This event handler is triggered after a customer clicks the Pay button. The event includes the customer's `billingAddress` as a `ShopPayContactField` object. The `ShopPayPaymentRequestSessionSubmit` mutation must be invoked, then `completePaymentConfirmationRequest()` must be called afterwards.
`completePaymentConfirmationRequest`	`(args: ShopPayPaymentRequestUpdate) => void`	This function is used to confirm that Shopify must proceed with payment. If there are any errors, they must be provided in the `errors` field. If `updatedPaymentRequest` is given, `errors` must also be given.
`paymentcomplete`	Event handler	This event handler is triggered after Shopify successfully processes a payment. The event payload has a `.processingStatus` field of type `ShopPayPaymentRequestReceiptCompleted`.
`paymentattemptfailed`	Event handler	This event handler is triggered when a payment attempt has failed. The event payload has a `.error` field with details about why the payment attempt failed.
`close`	`() => void`	This function cancels the session and closes the popup.
`windowclosed`	Event handler	This event handler is triggered after the checkout window is closed.

Anchor to [object Object]`ShopPayPaymentRequest`

A payment request is the primary means of communication between your system and Shop Pay.

Note

The frontend ShopPayPaymentRequest, used to display the payment request in the Shop Pay popup, is different from the backend ShopPayPaymentRequestInput, used in mutations as part of payment processing. Make sure to use the correct type for each context.

The following interface defines the properties of a ShopPayPaymentRequest:

interface ShopPayPaymentRequest {

supportedDeliveryMethodTypes?: ShopPayDeliveryMethodType[];

selectedDeliveryMethodType?: ShopPayDeliveryMethodType;

pickupLocations?: ShopPayPickupLocation[];

paymentMethod?: string;

discountCodes: string[];

lineItems: ShopPayLineItem[];

shippingLines: ShopPayShippingLine[];

deliveryMethods: ShopPayDeliveryMethod[]

locale: ShopPayLocale;

presentmentCurrency: ShopPayCurrencyCode;

subtotal: ShopPayMoney;

discounts?: ShopPayDiscountLine[];

totalShippingPrice?: ShopPayTotalShippingPrice;

totalTax?: ShopPayMoney;

total: ShopPayMoney;

}

Field name	Type	Description
`supportedDeliveryMethodTypes` optional	`ShopPayDeliveryMethodType[]`	The supported delivery method types for this checkout. Defaults to `["SHIPPING"]`.
`selectedDeliveryMethodType` optional	`ShopPayDeliveryMethodType`	The selected delivery method type.
`pickupLocations` optional	`ShopPayPickupLocation[]`	The available pickup locations when the selected delivery method type is `PICKUP`.
`paymentMethod` optional	`string`	The one-time-use payment token, included only in the `paymentconfirmationrequested` event.
`discountCodes` required	`string[]`	All applied discount codes, displayed under the discount code field as tags.
`lineItems` required	`ShopPayLineItem[]`	The line items to display.
`shippingLines` required	`ShopPayShippingLine[]`	The shipping line items to display.
`deliveryMethods` required	`ShopPayDeliveryMethod[]`	The available delivery methods.
`locale` required	`ShopPayLocale`	An ISO 639-1 language code, such as `en`, used to inform the display of instructions and amounts.
`presentmentCurrency` required	`ShopPayCurrencyCode`	An ISO 4217 currency code for the transaction, including legacy and non-standard codes.
`subtotal` required	`ShopPayMoney`	The subtotal of the line items, calculated as the sum of the `finalLinePrice` from all lines.
`discounts` optional	`ShopPayDiscountLine[]`	All discounts applied to the subtotal. These must be positive values.
`totalShippingPrice` optional	`ShopPayTotalShippingPrice`	The total shipping price after all applicable discounts, not including tax.
`totalTax` optional	`ShopPayMoney`	The total tax from all line items and shipping charges.
`total` required	`ShopPayMoney`	The grand total includes all applicable discounts, shipping charges, and taxes. The customer is charged this amount.

Anchor to [object Object]`ShopPayDeliveryMethodType`

The ShopPayDeliveryMethodType can be one of the following values:

PICKUP: The customer buys online and picks up the order.
SHIPPING: The customer's order is shipped.

Anchor to [object Object]`ShopPayLineItem`

Represents line items in a payment request. Includes cart line items, order-level line items such as discounts and taxes, and the grand total.

interface ShopPayLineItem {

label: string;

quantity: number;

sku?: string;

requiresShipping?: boolean;

image?: ShopPayLineItemImage;

originalItemPrice: ShopPayMoney;

itemDiscounts?: ShopPayDiscountLine[];

finalItemPrice: ShopPayMoney;

originalLinePrice: ShopPayMoney;

lineDiscounts?: ShopPayDiscountLine[];

finalLinePrice: ShopPayMoney;

}

Field name	Type	Description
`label` required	`string`	The label for the line item.
`quantity` required	`number`	The quantity of the line item.
`sku` optional	`string`	The merchandise SKU if needed for inventory tracking and reporting.
`requiresShipping` optional	`boolean`	Whether the line item requires shipping. Defaults to `true`.
`image` optional	`ShopPayLineItemImage`	The image associated with the line item.
`originalItemPrice` required	`ShopPayMoney`	The original price of the item before any applicable discounts.
`itemDiscounts` optional	`ShopPayDiscountLine[]`	All discounts applied to the item. These must be positive values.
`finalItemPrice` required	`ShopPayMoney`	The final price of the item after all applicable discounts.
`originalLinePrice` required	`ShopPayMoney`	The original line price before any applicable discounts, calculated as the original item price multiplied by quantity.
`lineDiscounts` optional	`ShopPayDiscountLine[]`	All discounts applied to the line item.
`finalLinePrice` required	`ShopPayMoney`	The final price of the line item based on quantity * item price including all applicable discounts.

Anchor to [object Object]`ShopPayLineItemImage`

The image associated with the line item.

interface ShopPayLineItemImage {

url: string;

alt?: string;

}

Field name	Type	Description
`url` required	`string`	The URL of the image. Recommended: 128x128px, 1:1 ratio image.
`alt` optional	`string`	The alt text associated with the image.

Anchor to [object Object]`ShopPayTotalShippingPrice`

Represents the total shipping price in a payment request.

interface ShopPayTotalShippingPrice {

discounts?: ShopPayDiscountLine[];

originalTotal?: ShopPayMoney;

finalTotal: ShopPayMoney;

}

Field name	Type	Description
`discounts` optional	`ShopPayDiscountLine[]`	All discounts applied to the shipping price. These must be positive values.
`originalTotal` optional	`ShopPayMoney`	The original total shipping price. Used to show shipping price before any applicable discounts are applied, and must be included for all non-free shipping methods.
`finalTotal` required	`ShopPayMoney`	The final total shipping price. Price after all applicable discounts.

Anchor to [object Object]`ShopPayDiscountLine`

Represents discount lines in a payment request.

interface ShopPayDiscountLine {

label: string;

amount: ShopPayMoney;

}

Field name	Type	Description
`label` required	`string`	The label for the discount line.
`amount` required	`ShopPayMoney`	The amount of the discount as a positive value.

Anchor to [object Object]`ShopPayShippingLine`

Represents shipping line items in a payment request.

interface ShopPayShippingLine {

label: string;

amount: ShopPayMoney;

code: string;

}

Field name	Type	Description
`label` required	`string`	The label for the shipping line item.
`amount` required	`ShopPayMoney`	The amount of the shipping line item.
`code` required	`string`	The service code of the shipping rate. Corresponds to `ShopPayDeliveryMethod#code`.

Anchor to [object Object]`ShopPayMoney`

Represents an amount and the associated currency.

Field name	Type	Description
`amount` required	`number`
`currencyCode` required	`ShopPayCurrencyCode`

Anchor to [object Object]`ShopPayContactField`

Represents contact information for shipping or billing addresses. This interface is used to capture customer shipping and contact details during the checkout process.

Field name	Type	Description
`countryCode` required	`string`	The country ISO-3166 code of the contact.
`postalCode` optional	`string`	The postal code of the contact.
`provinceCode` optional	`string`	The province (or state) ISO-3166 code of the contact.
`city` required	`string`	The city of the contact.
`firstName` optional	`string`	The first name of the contact.
`lastName` required	`string`	The last name of the contact.
`address1` required	`string`	The address of the contact.
`address2` optional	`string`	The address2 of the contact.
`phone` optional	`string`	The phone number of the contact.
`email` optional	`string`	The email address of the contact.
`companyName` optional	`string`	The company name of the contact.

Anchor to [object Object]`ShopPayPickupLocation`

Represents an available order pickup location. Pickup locations are displayed to a customer if they select PICKUP as the delivery method type.

interface ShopPayPickupLocation {

label: string;

detail: string;

code: string;

amount: ShopPayMoney;

readyExpectationLabel?: string;

proximityLabel?: string;

}

Field name	Type	Description
`label` required	`string`	The label for the pickup location.
`detail` required	`string`	The detail describing the pickup location.
`code` required	`string`	The code for the pickup location used to uniquely identify it.
`amount` required	`ShopPayMoney`	The amount of the pickup.
`readyExpectationLabel` optional	`string`	The description of when the order is ready for pickup.
`proximityLabel` optional	`string`	The description for the proximity of the pickup location relative to the customer.

Anchor to [object Object]`ShopPayDeliveryMethod`

interface ShopPayDeliveryMethod {

code: string;

label: string;

detail?: string;

amount: ShopPayMoney;

minDeliveryDate?: ISO8601Date;

maxDeliveryDate?: ISO8601Date;

deliveryExpectationLabel?: string;

}

Field name	Type	Description
`code` required	`string`	The service code of the shipping rate.
`label` required	`string`	The service name of the shipping rate.
`detail` optional	`string`	The description of the shipping rate.
`amount` required	`ShopPayMoney`	The total price amount of the shipping rate.
`minDeliveryDate` optional	`ISO8601Date`	The minimum delivery date. ISO 8601-encoded date string. Required unless `deliveryExpectationLabel` is provided.
`maxDeliveryDate` optional	`ISO8601Date`	The maximum delivery date. ISO 8601-encoded date string. Required unless `deliveryExpectationLabel` is provided.
`deliveryExpectationLabel` optional	`string`	If provided, is displayed as further detail for expected delivery, replacing the calculated delivery estimate.

Anchor to [object Object]`ShopPayPaymentRequestUpdate`

Represents an updated state of the checkout. At least one of an updated payment request and an array of errors should be provided.

Field name	Type	Description
`updatedPaymentRequest` optional	`ShopPayPaymentRequest`	The updated payment request. If not provided, the current payment request continues to be used.
`errors` optional	`ShopPayUserError[]`	An array of errors.

Anchor to [object Object]`PickupLocationChangedEvent`

Dispatched when a customer changes their pickup location.

interface PickupLocationChangedEvent extends Event {

pickupLocation: ShopPayPickupLocation;

}

Field name	Type	Description
`pickupLocation` required	`ShopPayPickupLocation`	The customer's pick up location.

Anchor to [object Object]`PickupLocationFilterChangedEvent`

Dispatched when a customer changes their pickup location filter.

interface PickupLocationFilterChangedEvent extends Event {

buyerLocation: ShopPayBuyerLocation;

}

Field name	Type	Description
`buyerLocation` required	`ShopPayBuyerLocation`	The customer's location used to filter pickup locations.

Anchor to [object Object]`DeliveryMethodTypeChangedEvent`

Dispatched when a customer changes their delivery method type.

interface DeliveryMethodTypeChangedEvent extends Event {

deliveryMethodType: ShopPayDeliveryMethodType;

}

Field name	Type	Description
`deliveryMethodType` required	`ShopPayDeliveryMethodType`	The delivery method type selected by the user.

Anchor to [object Object]`ShopPayBuyerLocation`

Represents a customer's location. Use this to set the available pickup locations.

interface ShopPayBuyerLocation {

address1?: string;

address2?: string;

city?: string;

provinceCode?: string;

countryCode?: string;

postalCode?: string;

coordinates?: {

latitude: number;

longitude: number;

};

}

Field name	Type	Description
`address1` optional	`string`	The address of the contact.
`address2` optional	`string`	The address2 of the contact.
`city` optional	`string`	The city of the contact.
`provinceCode` optional	`string`	The province (or state) ISO-3166 code of the contact.
`countryCode` optional	`string`	The country ISO-3166 code of the contact.
`postalCode` optional	`string`	The postal code of the contact.
`coordinates.latitude` optional	`number`	The latitude of the customer's location.
`coordinates.longitude` optional	`number`	The longitude of the customer's location.

Anchor to [object Object]`ShopPayPaymentConfirmationRequestedEvent`

Dispatched when a customer clicks Pay now to confirm their payment. This event includes the customer's billing address.

interface ShopPayPaymentConfirmationRequestedEvent extends Event {

billingAddress: ShopPayContactField;

}

Field name	Type	Description
`billingAddress` required	`ShopPayContactField`	The customer's billing address and contact info.

Anchor to [object Object]`ShopPayPaymentRequestReceiptCompleted`

A successful completed receipt. The status is completed. This event only occurs if the payment is successfully processed.

interface ShopPayPaymentRequestReceiptCompleted {

completedAt: ISO8601Date;

billingAddress?: {

countryCode: string;

postalCode?: string;

provinceCode?: string;

city: string;

firstName?: string;

lastName: string;

address1: string;

address2?: string;

phone?: string;

email?: string;

companyName?: string;

};

creditCardDetails?: {

brand?: string;

lastDigits?: string;

};

paymentType: "SHOP_PAY" | "SHOPIFY_INSTALLMENTS";

accountUrl?: string;

status: "completed";

}

Field name	Type	Description
`completedAt` required	`ISO8601Date`	The date the receipt was completed.
`billingAddress` optional	`ShopPayContactField`	The billing address of the customer. When present, `countryCode`, `city`, `lastName`, and `address1` are required.
`creditCardDetails` optional	`{brand?: string, lastDigits?: string}`	The credit card details of the customer.
`paymentType` required	`"SHOP_PAY" or "SHOPIFY_INSTALLMENTS"`	The type of payment used.
`accountUrl` optional	`string`	The URL to the customer's account.
`status` required	`"completed"`	The status of the receipt.

Anchor to [object Object]`ShopPayPaymentAttemptFailedEvent`

Dispatched when a payment attempt has failed. This can happen due to various reasons such as insufficient funds, invalid payment details, or other payment processing errors.

Caution

Buyers have the option to select a different payment method to retry their checkout after a failure. Don't call session.close() so that users can retry with a new payment method without disrupting their session.

interface ShopPayPaymentAttemptFailedEvent extends Event {

error: {

errorCode: string;

reason: string;

};

}

Field name	Type	Description
`error` required	`{errorCode: string, reason: string}`	The reason why the payment attempt failed.

Anchor to [object Object]`ShopPayUserError`

Represents an error that's surfaced to the user during checkout.

The following images show how each error type appears in the Shop Pay dialog:

generalError:

discountCodeError:

shippingAddressError:

Field name	Type	Description
`type` required	`'generalError'` or `'discountCodeError'` or `'shippingAddressError'`	The context of the error.
`message` optional	`string`	The localized message shown to the user.

generalError: These errors are shown at the top of the checkout. We recommend setting your own message. The default error text is "Something went wrong. Please close Shop Pay and try again".
discountCodeError: These errors are shown near discount code entry, for example, to indicate that a discount code is expired. We recommend setting your own message. The default error text is "Enter a valid discount code".
shippingAddressError: These errors are shown near shipping address selection, for example, to indicate that the selected shipping address can't be delivered to. We recommend setting your own message. The default error text is "Shipping not available for selected address".

Note

A maximum of two errors can be displayed at any given time. If more than two errors are provided, only the first two are shown. Each error message has a character limit of 500; any message exceeding this limit is truncated. Only plain text is supported for error messages. Any HTML or other formatting is removed.

Anchor to Confirmation flowConfirmation flow

After a customer clicks Pay, payment confirmation follows this sequence:

The paymentconfirmationrequested event is triggered on your frontend, containing the paymentMethod token.
Your server runs the ShopPayPaymentRequestSessionSubmit mutation to authorize payment processing.
Your system performs a final validation (for example, confirming the cart total and inventory) and your frontend calls session.completePaymentConfirmationRequest() to continue. If validation fails, call completePaymentConfirmationRequest() with an errors array to surface the error to the buyer in the Shop Pay popup. Refer to the paymentconfirmationrequested listener example for the error-handling pattern.
The paymentcomplete event is dispatched after Shopify finishes processing.

Based on the payment capture configuration in the Shopify admin's Payments settings, the payment is processed as authorized or capture. If manual capture is configured, you must call the GraphQL Admin API's orderCapture mutation to finalize the payment.

When an order is created in Shopify, it might not be immediately available to query, and the orders/create webhook might not fire immediately. Don't rely on either for real-time functionality. Refer to Recovering from errors to make your app resilient to webhook delivery issues.

Was this page helpful?

Anchor to [object Object]ShopPayPaymentRequestSession

Anchor to [object Object]ShopPayPaymentRequest

Anchor to [object Object]ShopPayDeliveryMethodType

Anchor to [object Object]ShopPayLineItem

Anchor to [object Object]ShopPayLineItemImage

Anchor to [object Object]ShopPayTotalShippingPrice

Anchor to [object Object]ShopPayDiscountLine

Anchor to [object Object]ShopPayShippingLine

Anchor to [object Object]ShopPayMoney

Anchor to [object Object]ShopPayContactField

Anchor to [object Object]ShopPayPickupLocation

Anchor to [object Object]ShopPayDeliveryMethod

Anchor to [object Object]ShopPayPaymentRequestUpdate

Anchor to [object Object]PickupLocationChangedEvent

Anchor to [object Object]PickupLocationFilterChangedEvent

Anchor to [object Object]DeliveryMethodTypeChangedEvent

Anchor to [object Object]ShopPayBuyerLocation

Anchor to [object Object]ShopPayPaymentConfirmationRequestedEvent

Anchor to [object Object]ShopPayPaymentRequestReceiptCompleted

Anchor to [object Object]ShopPayPaymentAttemptFailedEvent

Anchor to [object Object]ShopPayUserError

Anchor to Confirmation flowConfirmation flow

Anchor to [object Object]`ShopPayPaymentRequestSession`

Anchor to [object Object]`ShopPayPaymentRequest`

Anchor to [object Object]`ShopPayDeliveryMethodType`

Anchor to [object Object]`ShopPayLineItem`

Anchor to [object Object]`ShopPayLineItemImage`

Anchor to [object Object]`ShopPayTotalShippingPrice`

Anchor to [object Object]`ShopPayDiscountLine`

Anchor to [object Object]`ShopPayShippingLine`

Anchor to [object Object]`ShopPayMoney`

Anchor to [object Object]`ShopPayContactField`

Anchor to [object Object]`ShopPayPickupLocation`

Anchor to [object Object]`ShopPayDeliveryMethod`

Anchor to [object Object]`ShopPayPaymentRequestUpdate`

Anchor to [object Object]`PickupLocationChangedEvent`

Anchor to [object Object]`PickupLocationFilterChangedEvent`

Anchor to [object Object]`DeliveryMethodTypeChangedEvent`

Anchor to [object Object]`ShopPayBuyerLocation`

Anchor to [object Object]`ShopPayPaymentConfirmationRequestedEvent`

Anchor to [object Object]`ShopPayPaymentRequestReceiptCompleted`

Anchor to [object Object]`ShopPayPaymentAttemptFailedEvent`

Anchor to [object Object]`ShopPayUserError`