A list of the Shop Pay Wallet API endpoints and their parameters.
Type signatures throughout use GraphQL-style syntax. The bang (!
) operator represents a required, non-nullable field. Absence of the bang operator implies a nullable field.
The base URL for all authorization requests is https://shop.app
Query Parameters
|
||
Key
|
Type
|
Description
|
response_type
|
String! |
The value of "code". |
client_id
|
String! |
To be provided by Shop Pay. |
scope
|
String! |
A space-delimited list of scopes. Refer to Authorization scopes for a list of allowed scopes. |
redirect_uri
|
String! |
Client redirect URI, once the flow is complete. |
login_hint
|
String |
You can speed up the authorization flow by telling Shop Pay about the customer. Shop Pay uses the login_hint to identify which customer is logging in. If you add the login_hint , and Shop Pay recognizes the login_hint , then the user doesn't need to provide their email and can skip ahead in the flow. The login_hint can be one of the following values:
|
state
|
String |
An opaque value used by the client to maintain state between the request and callback. |
channel
|
String |
For clients with multiple experiences, a stable identifier for the user to recognize the experience. |
PKCE parameters
|
As defined in PKCE OAuth Extension RFC7636 Section 4.3 |
|
code_challenge
|
String |
Derived from the code_verifier, depending on the code_challenge_method below. |
code_challenge_method
|
String |
Based on RFC7636 Section 4.2 and Appendix A Method used to derive the code_challenge from the code_verifier. The only supported challenge method is |
Example
|
||
cURL |
Basic ```bash curl --location --request GET 'https://shop.app/pay/authorize?response_type=code&client_id=ch4rl1nh0&scope=uma:pay:address:read uma:pay:credit_card:read uma:pay:credit_card:read_payment_session&redirect_uri=http://awesome-partner-app.io/pay/wallet/redirect&state=123456' \ ```with Login Hint ```bash curl --location --request GET 'https://shop.app/pay/authorize?response_type=code&client_id=ch4rl1nh0&scope=uma:pay:address:read uma:pay:credit_card:read uma:pay:credit_card:read_payment_session&redirect_uri=http://awesome-partner-app.io/pay/wallet/redirect&state=123456&login_hint=us3r-uu1d' \ ``` |
Type
|
Response Code
|
Details
|
Success Response |
302 Found
|
Redirect with authorization info in the query params. Authorization codes are single use and expire after 5 minutes. If it takes more than 5 minutes to complete the request for authorization, you will have to restart the flow with the User. |
Error Response |
302 Found
|
Redirect with error info in the query params, where
For more information on the authorization error response, see RFC6749 section 4.1.2.1. |
Error Response |
400 Bad request
|
The error response will include information about the failure. Example: ``` { "error":The request isn't redirected when
For more information on authorization error responses, refer to RFC6749 section 5.2. |
The base URL for all token requests is https://accounts.shop.app
HTTP Headers
|
||
Authorization
|
The word |
|
Content-Type
|
application/x-www-form-urlencoded
|
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Request Body
|
||
Key
|
Type
|
Description
|
grant_type
|
String! |
The value of "authorization_code". |
redirect_uri
|
String! |
The redirect URI from the previous step. |
code
|
String! |
The Authorization Code obtained in the previous step. |
PKCE parameters
|
As defined in PKCE OAuth Extension RFC7636 Section 4.3 |
|
code_verifier
|
String |
The code_verifier value. |
Example
|
||
cURL | ```bash curl --request POST 'https://accounts.shop.app/oauth/token' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Authorization: Basic Y2g0secretCodeOjEyM2FiYw==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=123authcode456' \ --data-urlencode 'redirect_uri=http://awesome-partner-app.io/pay/wallet/redirect' \ --data-urlencode 'code_verifier=Pkc3C0d3V3r1fi13r' ``` |
Response Code
|
Details
|
200 OK
|
Success response with token info. |
400 Bad Request
|
The error response will include information about the failure. Example: ``` { "error":Where
For more information on the authorization error response, see RFC6749 section 5.2. |
401 Unauthorized
|
If authorization with the provided client credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
HTTP Headers
|
||
Authorization
|
The word |
|
Content-Type
|
application/x-www-form-urlencoded
|
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Request Body
|
||
Key
|
Type
|
Description
|
grant_type
|
String! |
The value of |
refresh_token
|
String! |
Previously obtained refresh token. |
Example
|
||
cURL | ```bash curl --request POST 'https://accounts.shop.app/oauth/token' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Authorization: Basic Y2g0cmwxbmgwOjEyM2FiYw==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'refresh_token=abcd12345efghi6789' ``` |
Response Code
|
Details
|
200 OK
|
Success response with refreshed token info. |
400 Bad Request
|
The error response will include information about the failure. Example: ``` { "error":Where
For more information on the authorization error response, see RFC6749 section 5.2. |
401 Unauthorized
|
If authorization with the provided client credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
HTTP Headers
|
||
Authorization
|
The word |
|
Content-Type
|
application/x-www-form-urlencoded
|
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Request Body
|
||
Key
|
Type
|
Description
|
token
|
String! |
The string value of the token, either an access token or a refresh token. |
token_type_hint
|
String! |
Valid values are |
Example
|
||
cURL | ```bash curl --location --request POST 'https://accounts.shop.app/oauth/revoke' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Authorization: Basic Q2wxM250MUQ6MTIzYWJj' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'token=abcd12345efghi6789' \ --data-urlencode 'token_type_hint=access_token' ``` |
Response Code
|
Details
|
200 OK
|
Success response when token is revoked successfully, or if the token was invalid anyway. For more information on the token revocation response, see RFC7009 section 2.2 |
400 Bad Request
|
The error response will include information about the failure. Example: ``` { "error":Where
For more information on the authorization error response, see RFC6749 section 5.2. |
401 Unauthorized
|
If authorization with the provided client credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
HTTP Headers
|
||
Authorization
|
The word |
|
Content-Type
|
application/x-www-form-urlencoded
|
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Request Body
|
||
Key
|
Type
|
Description
|
token
|
String! |
The string value of the token, either an access token or a refresh token. |
token_type_hint
|
String! |
Valid values are |
Example
|
||
cURL | ```bash curl --location --request POST 'https://accounts.shop.app/oauth/introspect' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Authorization: Basic Q2wxM250MUQ6MTIzYWJj' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'token=abcd12345efghi6789' \ --data-urlencode 'token_type_hint=access_token' ``` |
Response Code
|
Details
|
200 OK
|
Success response when token is successfully introspected. |
400 Bad Request
|
The error response will include information about the failure. Example: ``` { "error":Where
For more information on the authorization error response, see RFC6749 section 5.2. |
401 Unauthorized
|
If authorization with the provided client credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
The base URL for all wallet and order requests is https://shop.app
HTTP Headers
|
||
Authorization
|
This is User-scoped authorization via an OAuth Access Token generated via the OAuth authorization flow. |
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Example
|
||
cURL | ```bash curl --location --request GET 'https://shop.app/pay/wallet' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Authorization: Bearer 123accesstoken456' ``` |
Response Code
|
Details
|
200 OK
|
Success response. See below for an example. |
401 Unauthorized
|
If authorization with the provided User credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
Responses from this endpoint will provide the card network in upper case. See the full list of supported card networks for more options.
HTTP Headers
|
||
Authorization
|
This is User-scoped authorization via an OAuth Access Token generated via the OAuth authorization flow. We require User-scoped auth to confirm an Order so that we can associate the User and the Order in Shop Pay's systems. This association can only be set on creation and it cannot be changed. |
|
Content-Type
|
application/json
|
|
Certificate
|
Base64-encoded string of the public certificate used for one-time encryption of the payment information returned in the API response. To learn how to generate an encryption certificate or for detailed instructions on formatting, refer to Payment method encryption. This header is required if |
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
JSON Request Body
|
||
Key
|
Type
|
Description
|
order_ids
|
[String!]! |
For all Order types, a list of order IDs from your internal systems. These `order_id`s are what we use to link your the Shop Pay interactions with the corresponding checkout on Shopify Core's Admin API. So the `order_id` you provide here must match the `source_identifier` you provide to the [checkout resource](/docs/api/admin-rest/2022-04/resources/checkout). These identifiers should uniquely identify the order on your system accross any merchant you work with. For instance, if you use identifer `123` for an order with Merchant A, you cannot use `123` on a later order, even with Merchant B. |
tokenization_type
|
String! |
A specification of the tokenization method. One of the following allowed values:
|
Example
|
||
cURL | ```bash curl --location --request POST 'https://shop.app/pay/wallet/orders' \ --header 'User-Agent: ShopPay/production Ruby/3.0.1' \ --header 'Certificate: b4s364Str1ng' \ --header 'Authorization: Bearer 123accesstoken456' \ --header 'Content-Type: application/json' \ --data-raw '{ "order_ids": ["1234"], "tokenization_type": "SESSION" }' ``` |
Response Code
|
Details
|
200 OK
|
Success response. See below for an example. |
400 Bad Request
|
Generic error when we fail to parse all or part of the request. |
401 Unauthorized
|
If authorization with the provided User credentials fails. |
403 Forbidden
|
If we deny access to the resource. Common causes include:
|
429 Too Many Requests
|
Rate limit response. |
Responses from this endpoint will provide the card network in upper case. See the full list of supported card networks for more options.
HTTP Headers
|
||
Authorization
|
The word |
|
Content-Type
|
application/json
|
|
User-Agent
|
A string identifying the service of origin making the request with optional runtime metadata. For example:
|
|
Path Parameters
|
||
id
|
The unique identifier of the Order in your system. One of the |
|
JSON Request Body
|
The current Order state. Each update is a reset of the Order state. The top-level JSON object
should reflect the shape defined by the Example: ```json { "cancelReason": null, "cancelledAt": null, "createdAt": "2021-01-01T00:00:00.000Z", "deliveryMethods": [], "fulfillments": [], "lineItems": [], "merchant": { "name": "Snowdevil", "url": "http://snowdevil.ca/" }, "paymentStatus": "PENDING", "refunds": [], "shipmentStatus": "UNSHIPPED", "total": { ... "totalPrice": { price: "0.00", currencyCode: "USD" } }, "updatedAt": "2021-01-01T00:00:00.000Z" } ``` |
|
Example
|
||
cURL |
```bash
curl --location --request POST 'https://shop.app/pay/wallet/orders/1234' \
--header 'User-Agent: ShopPay/production Ruby/3.0.1' \
--header 'Authorization: Basic Y2g0cmwxbmgwOjEyM2FiYw==' \
--header 'Content-Type: application/json' \
--data-raw ' {
"total": {
"totalTax": {
"amount": "2.22",
"currencyCode": "USD"
},
"totalPrice": {
"amount": "2.20",
"currencyCode": "USD"
},
"cartDiscounts": {
"amount": "0.00",
"currencyCode": "USD"
},
"totalDiscounts": {
"amount": "0.00",
"currencyCode": "USD"
},
"lineItemDiscounts": {
"amount": "0.00",
"currencyCode": "USD"
},
"shippingDiscounts": {
"amount": "0.00",
"currencyCode": "USD"
},
"lineItemSubtotalPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"shippingSubtotalPrice": {
"amount": "1.00",
"currencyCode": "USD"
}
},
"refunds": [],
"merchant": {
"url": "https://snowdevil.ca/",
"name": "Snowdevil",
"merchantId": "315d97c3-aeb2-4e7b-bdf3-d0fd8e510607"
},
"createdAt": "2021-08-10T13:51:05Z",
"lineItems": [
{
"gtin": "8102172c-0c6e-408b-b3fb-6646de1a52e8",
"imageUrl": "https://example.com/image.jpg",
"quantity": 1,
"taxLines": [
{
"price": {
"amount": "0.10",
"currencyCode": "USD"
},
"title": "Line item sales tax"
}
],
"unitPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"lineItemId": "85eb85fd-77f6-4493-9df6-dfa24a2f27b2",
"productUrl": "https://example.com/snowboard",
"totalPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"description": "An example line item",
"productTitle": "Snowboard",
"originalUnitPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"originalTotalPrice": {
"amount": "1.00",
"currencyCode": "USD"
}
}
],
"updatedAt": "2021-08-10T13:51:05Z",
"fulfillments": [
{
"name": "Shipment",
"status": "IN_TRANSIT",
"inTransitAt": "2021-08-10T13:51:05Z",
"lineItemIds": [
"47ce3714-8a3e-4fda-babe-f5f302d02b6d"
],
"trackingInfo": {
"carrierCode": "USPS",
"trackingUrl": "https://example.com/tracking",
"trackingNumber": "00594b99-b7c3-4454-9e56-b6dd4bcb2bc8"
},
"fulfillmentId": "62144d7e-aef5-4132-bdc4-581cc2b4a4f2",
"estimatedDeliveryAt": "2021-08-11T13:51:05Z"
}
],
"paymentStatus": "PAID",
"shipmentStatus": "SHIPPED",
"deliveryMethods": [
{
"name": "Delivery purchase",
"taxLines": [
{
"price": {
"amount": "0.10",
"currencyCode": "USD"
},
"title": "Shipment sales tax"
}
],
"unitPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"totalPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"lineItemIds": [
"47ce3714-8a3e-4fda-babe-f5f302d02b6d"
],
"deliveryMethodId": "ccf15282-492d-4f2f-84c6-2819d65ea048",
"originalUnitPrice": {
"amount": "1.00",
"currencyCode": "USD"
},
"originalTotalPrice": {
"amount": "1.00",
"currencyCode": "USD"
}
}
]
}'
```
|
Response Code
|
Details
|
204 No Content
|
Success response. |
400 Bad Request
|
Generic error when we fail to parse all or part of the request. |
401 Unauthorized
|
If authorization with the provided client credentials fails. |
403 Forbidden
|
If we deny access to the resource. A common cause is a missing |
404 Not Found
|
If an Order could not be found to update. |
422 Unprocessable Entity
|
If the update request parameters fail validation. The error response will include information about the validation failures. Example: ``` { "errors": [ { "field": "createdAt", "code": "field_missing", "message": "Field createdAt cannot be null." } ] } ``` |
429 Too Many Requests
|
Rate limit response. |
LineItems
in an Order
.
Key
|
Type
|
Description
|
deliveryMethodId
|
String! |
A stable identifier for the DeliveryMethod in your internal systems. |
description
|
String |
Description of the purchased delivery. |
lineItemIds
|
[String!]! |
The line items covered by this delivery. Each item in this array should map to one of the |
name
|
String! |
Name of the purchased delivery. |
originalTotalPrice
|
Money! |
The total price of delivery for all the included line item units without any discounts or taxes applied. Computed as: originalUnitPrice * length(lineItemIds) |
originalUnitPrice
|
Money |
The delivery cost for a single line item unit without any discounts or taxes applied. |
taxLines
|
[TaxLine!]! |
All taxes applied to the DeliveryMethod. |
totalPrice
|
Money! |
The total price of delivery for all the included line item units with discounts applied. This price does not include taxes. Computed as: unitPrice * length(lineItemIds) |
unitPrice
|
Money |
The delivery cost for a single line item unit with discounts applied. This price does not include taxes. |
LineItems
in an Order
.
Key
|
Type
|
Description
|
deliveredAt
|
DateTime |
The time when the LineItems in the Fulfillment were delivered to the destination address. This field is always optional, since it may not be possible to capture the time of delivery within your systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
description
|
String |
Description of the Fulfillment. |
estimatedDeliveryAt
|
DateTime |
The estimated delivery time for the Fulfillment as captured in your internal systems. This field is always optional, since it may not be possible to capture the estimated time of delivery within your systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
fulfilledAt
|
DateTime |
The time the Fulfillment is first received up by the delivery carrier as captured in your internal systems. This field is always optional, since it may not be possible to capture the fulfillment time within your systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
fulfillmentId
|
String! |
A stable identifier for the Fulfillment in your internal systems. |
inTransitAt
|
DateTime |
The time the Fulfillment is put in transit by the delivery carrier as captured in your internal systems. This field is always optional, since it may not be possible to capture the in-transit time within your systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
lineItemIds
|
[String!]! |
The LineItems that will be delivered as part of this Fulfillment. Each item in this array should map to one of the |
name
|
String! |
Name of the Fulfillment. |
status
|
String! |
The latest status of the Fulfillment as captured by your systems. One of the following allowed values:
|
trackingInfo
|
TrackingInfo |
Tracking data for the Fulfillment from the delivery carrier, if available. |
Order
.
Key
|
Type
|
Description
|
description
|
String |
Description of the product. |
gtin
|
String! |
GTIN (Global Trade Item Number) or UPC code. |
imageUrl
|
String! |
URL to an image thumbnail of the product. |
lineItemId
|
String! |
A stable identifier for the line item from your internal systems. |
originalTotalPrice
|
Money! |
The total price of all LineItem units without any discounts or taxes applied. Computed as: originalUnitPrice * quantity |
originalUnitPrice
|
Money! |
The price of a single LineItem unit without any discounts or taxes applied. |
productTitle
|
String! |
Name of the product. |
productUrl
|
String! |
URL linking to the product on the surface it was purchased. |
quantity
|
Int! |
The quantity of this LineItem purchased. |
taxLines
|
[TaxLine!]! |
All taxes applied to the LineItem. |
totalPrice
|
Money! |
The total price of all LineItem units with discounts applied. This price does not include taxes. Computed as: unitPrice * quantity |
unitPrice
|
Money! |
The price of a single LineItem unit with discounts applied. This price does not include taxes. |
variantTitle
|
String |
Optional modifier for the product title. For example: "Size: Medium". |
Key
|
Type
|
Description
|
name
|
String! |
The name of the Merchant. |
description
|
String |
A short description of the Merchant. |
logoUrl
|
String |
A URL linking to the Merchant's logo. |
merchantId
|
String! |
A stable identifier for the Merchant in your systems. |
url
|
String! |
A URL linking to the Merchant's online surface where the Order was placed. |
Key
|
Type
|
Description
|
amount
|
String! |
A decimal monetary value encoded as a String, where the decimal seperator is the |
currencyCode
|
String! |
Supported monetary currencies from ISO 4217. Example: |
Key
|
Type
|
Description
|
cancelReason
|
String |
The reason the Order was cancelled. One of the following allowed values:
|
cancelledAt
|
DateTime |
The time when the Order was cancelled in your internal systems. Null if the Order is has not been cancelled. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
createdAt
|
DateTime! |
The time when the Order was created in your internal systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
deliveryMethods
|
[DeliveryMethod!]! |
A list of deliveries purchased as part of the Order. |
fulfillments
|
[Fulfillment!]! |
A list shipment fulfillments via a delivery carrier for the items in the Order. Fulfillments do not need to map 1:1 with the DeliveryMethods. An Order can have a single DeliveryMethod split into multiple Fulfillments. |
lineItems
|
[LineItem!]! |
A list of products and associated metadata for the Order. |
merchant
|
Merchant! |
Info about the merchant associated with the Order. |
orderNumber
|
String! |
The customer-facing identifier for the Order that will be included on communications such as confirmation pages and emails. |
orderUrl
|
String |
A static link to a page on your platform where the customer can view details about the Order. |
paymentStatus
|
String! |
The current status of payment for the Order. One of the following allowed values:
|
refunds
|
[Refund!]! |
A list refunds applied to the Order. |
shipmentStatus
|
String! |
The overall shipment status for the Order. This is an aggregate of the status for each
|
total
|
OrderTotal! |
Enumerated total cost of the Order. |
updatedAt
|
DateTime! |
The time when the Order was last updated in your internal systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
Key
|
Type
|
Description
|
cartDiscounts
|
Money! |
The total of any discounts applied to the Order itself, rather than a specific LineItem or DeliveryMethod. |
lineItemDiscounts
|
Money! |
The total of all LineItem discounts in the Order. |
lineItemSubtotalPrice
|
Money! |
The total cost of all LineItems in the Order. This includes LineItem discounts and Order-level discounts ( Computed as: sum(lineItems[].totalPrice) + cartDiscounts |
shippingDiscounts
|
Money! |
The total of all discounts for all DeliveryMethods in the Order. |
shippingSubtotalPrice
|
Money! |
The total cost of all DeliveryMethods in the Order. This includes DeliveryMethod discounts. This does not include any Order-level discounts, line item costs, or taxes. Computed as: sum(deliveryMethods[].totalPrice) |
totalDiscounts
|
Money! |
The total of all discounts applied to the Order. Computed as: cartDiscounts + lineItemDiscounts + shippingDiscounts |
totalTax
|
Money! |
The total of all TaxLines for all LineItems and DeliveryMethods in the Order. Computed as: sum(lineItems[].taxLines[].price) + sum(deliveryMethods[].taxLines[].price) |
totalPrice
|
Money! |
The total cost of the Order, a combination of subtotal prices and taxes. Computed as: lineItemSubtotalPrice + shippingSubtotalPrice + totalTax |
Key
|
Type
|
Description
|
createdAt
|
DateTime! |
The time when the Refund was created in your internal systems. An ISO-8601 encoded UTC datetime string. Example value: "2019-07-03T20:47:55Z". |
description
|
String |
A short description of the Refund. |
refundId
|
String! |
A stable identifier for the Refund in your internal systems. |
refundLineItems
|
[RefundLineItem!]! |
The products and quantities of the Refund. |
totalRefund
|
Money! |
The total amount of the Refund. |
Key
|
Type
|
Description
|
lineItemId
|
String! |
A reference to one of the line items in the Order. This should map to one of the |
quantity
|
Int |
The number of line items refunded. |
Key
|
Type
|
Description
|
price
|
Money! |
The amount of the tax applied. |
title
|
String! |
A description of the tax line. |
Key
|
Type
|
Description
|
carrierCode
|
String! |
Representing the carrier doing the shipment. |
trackingNumber
|
String! |
Tracking number for the shipment. |
trackingUrl
|
String |
Tracking URL for the shipment. |