Skip to main content

GraphQL pre-payment

These mutations are used with the Storefront API to affect the Shop Pay payment request session.

Anchor to Example: ShopPayPaymentRequestSessionCreateExample: ShopPayPaymentRequestSessionCreate

Details about the ShopPayPaymentRequestSessionCreate mutation can be found on the dedicated Storefront API ShopPayPaymentRequestSessionCreate page.

API version

This example uses Storefront API version 2026-10 or later, where only sourceIdentifier is required. In earlier versions, paymentRequest is a required ShopPayPaymentRequestInput! argument, so you must still pass it when you create a session.

Mutation

mutation shopPayPaymentRequestSessionCreate($sourceIdentifier: String!) {
shopPayPaymentRequestSessionCreate(sourceIdentifier: $sourceIdentifier) {
shopPayPaymentRequestSession {
token
sourceIdentifier
checkoutUrl
}
userErrors {
field
message
}
}
}

Input

{
"sourceIdentifier": "xyz123"
}

Response

{
"shopPayPaymentRequestSessionCreate": {
"shopPayPaymentRequestSession": {
"sourceIdentifier": "xyz123",
"token": "db4eede13822684b13a607823b7ba40d",
"checkoutUrl": "https://shop.app/checkout/1/spe/db4eede13822684b13a607823b7ba40d/shoppay"
},
"userErrors": []
}
}

Anchor to ShopPayPaymentRequestSessionCreate ArgumentsShopPayPaymentRequestSessionCreate Arguments

ArgumentTypeDescription
sourceIdentifierString!A unique identifier for the source of the order.
paymentRequestShopPayPaymentRequestInputThe payment request details. Optional and deprecated in Storefront API version 2026-10 and later. Required (ShopPayPaymentRequestInput!) in earlier versions.
businessEntityIdStringThe full global ID of the business entity to process the payment through, such as gid://shopify/BusinessEntity/123, from the GraphQL Admin API businessEntities query. Omit it to use the store's primary business entity. Available in Storefront API version 2027-01 and later. Refer to Process payments through multiple business entities.

Source Identifier

The sourceIdentifier must be unique across all orders to ensure accurate tracking and referencing. For instance, it could be a unique ID associated with an order or checkout on your platform.

Anchor to ShopPayPaymentRequestSessionShopPayPaymentRequestSession

FieldTypeDescription
tokenStringThe unique token for the payment request session.
sourceIdentifierStringA unique identifier for the source of the order.
checkoutUrlStringThe URL for the checkout associated with the payment request session.
paymentRequestShopPayPaymentRequestThe payment request associated with the session. Deprecated in Storefront API version 2026-10 and later.
businessEntityIdStringThe ID of the business entity selected for the session. Returns null if no entity was selected or if the selected entity can't be found. If no entity was selected, then the store's primary business entity processes the payment. Available in Storefront API version 2027-01 and later.

Anchor to UserErrorsUserErrors

FieldTypeDescription
fieldStringThe field that caused the error.
codeUserErrorsShopPayPaymentRequestSessionUserErrorsCodeThe error code.
messageStringThe error message.

Anchor to Example: ShopPayPaymentRequestSessionBusinessEntityUpdateExample: ShopPayPaymentRequestSessionBusinessEntityUpdate

Details about the ShopPayPaymentRequestSessionBusinessEntityUpdate mutation can be found on the dedicated Storefront API ShopPayPaymentRequestSessionBusinessEntityUpdate page. This mutation is available in Storefront API version 2027-01 and later. For when to call it, refer to Process payments through multiple business entities.

Mutation

mutation shopPayPaymentRequestSessionBusinessEntityUpdate($token: String!, $businessEntityId: String!) {
shopPayPaymentRequestSessionBusinessEntityUpdate(token: $token, businessEntityId: $businessEntityId) {
shopPayPaymentRequestSession {
token
sourceIdentifier
checkoutUrl
businessEntityId
}
userErrors {
field
code
message
}
}
}

Input

{
"token": "db4eede13822684b13a607823b7ba40d",
"businessEntityId": "gid://shopify/BusinessEntity/123"
}

Response

{
"shopPayPaymentRequestSessionBusinessEntityUpdate": {
"shopPayPaymentRequestSession": {
"token": "db4eede13822684b13a607823b7ba40d",
"sourceIdentifier": "xyz123",
"checkoutUrl": "https://shop.app/checkout/1/spe/db4eede13822684b13a607823b7ba40d/shoppay",
"businessEntityId": "gid://shopify/BusinessEntity/123"
},
"userErrors": []
}
}

Anchor to ShopPayPaymentRequestSessionBusinessEntityUpdate ArgumentsShopPayPaymentRequestSessionBusinessEntityUpdate Arguments

ArgumentTypeDescription
tokenString!The unique token for the payment request session.
businessEntityIdString!The full global ID of the business entity to process the payment through, such as gid://shopify/BusinessEntity/123, from the GraphQL Admin API businessEntities query. To use the store's primary business entity, pass its ID.

You can change the business entity until you submit the payment, or after the latest payment attempt has failed. The mutation returns the updated ShopPayPaymentRequestSession.

Anchor to UserErrorsUserErrors

FieldTypeDescription
fieldStringThe field that caused the error.
codeUserErrorsShopPayPaymentRequestSessionUserErrorsCodeThe error code.
messageStringThe error message.

Anchor to Example: ShopPayPaymentRequestSessionSubmitExample: ShopPayPaymentRequestSessionSubmit

Details about the ShopPayPaymentRequestSessionSubmit mutation can be found on the dedicated Storefront API ShopPayPaymentRequestSessionSubmit page.

Mutation

mutation shopPayPaymentRequestSessionSubmit($token: String!, $paymentRequest: ShopPayPaymentRequestInput!, $idempotencyKey: String!, $orderName: String) {
shopPayPaymentRequestSessionSubmit(token: $token, paymentRequest: $paymentRequest, idempotencyKey: $idempotencyKey, orderName: $orderName) {
paymentRequestReceipt {
token
processingStatusType
}
userErrors {
field
message
}
}
}

Input

{
"token": "db4eede13822684b13a607823b7ba40d",
"paymentRequest": {
…
},
"idempotencyKey": "REPLACE_ME_WITH_A_UNIQUE_KEY",
}

Response

{
"shopPayPaymentRequestSessionSubmit": {
"paymentRequestReceipt": {
"token": "a607823b7ba40ddb4eede13822684b13",
"processingStatusType": "ready"
},
"userErrors": []
}
}

Anchor to ArgumentsArguments

FieldTypeDescription
tokenString!The unique token for the payment request session.
paymentRequestShopPayPaymentRequestInput!The payment request details.
idempotencyKeyString!A unique string (typically a UUID or similar identifier) that must be attached to the submit request to ensure that payment transactions occur only once. For more information, see idempotent requests.
orderNameStringThe name to be assigned to the order that is created from the payment request.

Anchor to PaymentRequestReceiptPaymentRequestReceipt

FieldTypeDescription
tokenStringThe unique token for the payment request receipt. This will be different than session token.
processingStatusTypeStringThe processing status of the payment request.
paymentRequestShopPayPaymentRequestThe details of the payment request.
shopUserShopPayPaymentRequestShopUserThe Shop user that authorized the payment request. Available in Storefront API version 2026-10 and later. Refer to Identify Shop users.
businessEntityIdIDThe ID of the business entity recorded when the payment request was submitted. Returns null if no entity was recorded or if the recorded entity can't be found. If no entity was recorded, then the payment went through the store's primary business entity. Available in Storefront API version 2027-01 and later. Refer to Process payments through multiple business entities.

Anchor to UserErrorsUserErrors

FieldTypeDescription
fieldStringThe field that caused the error.
codeUserErrorsShopPayPaymentRequestSessionUserErrorsCodeThe error code.
messageStringThe error message.
Was this page helpful?