Shopify¶
How a Shopify shop connects to a retailer, what the platform then does with it, and what can go wrong.
Before you connect¶
- You need a role that can manage provider accounts:
owneroradmin(see Tenants and members), and access to the retailer the shop belongs to. - The retailer must exist and not be archived. Create one with
createRetailer, or use one fromactableRetailers. - A retailer has at most one connected shop, and a shop belongs to one tenant and one retailer at a time.
- You need the shop's permanent domain,
<name>.myshopify.com. A custom storefront domain does not work. - Shopify shops connect only by installing the platform's Shopify app. Typing in credentials is refused (the connect
operation answers
BAD_REQUESTand says Shopify shops connect through the app install). Other ways to connect, such as an app the merchant owns, are not available yet.
Connect a shop¶
In the web app, open a retailer's page, choose "Connect a shop", and enter the shop domain. The app accepts snowdevil,
snowdevil.myshopify.com or a pasted admin URL and normalises it.
Through the API, the same flow has two steps.
1. Begin the install¶
mutation BeginShopifyInstall($shopDomain: String!, $retailerId: String!) {
beginShopifyInstall(shopDomain: $shopDomain, retailerId: $retailerId) {
installUrl
}
}
{ "shopDomain": "snowdevil.myshopify.com", "retailerId": "<retailerId>" }
installUrl is Shopify's authorize page for this shop. Send the browser there; the install is completed by a
redirect, so a script cannot finish it alone. Refusals:
| Code | Cause |
|---|---|
BAD_REQUEST |
The domain is not <name>.myshopify.com |
FORBIDDEN |
You cannot connect shops for that retailer |
SERVICE_UNAVAILABLE |
The Shopify app is not configured on this server |
2. Approve in Shopify¶
The merchant approves the app's access in Shopify, which redirects the browser to GET /api/shopify/oauth/callback. Two
rules apply:
- The person who finishes the install must be the same signed-in user who began it, with the same tenant active in their
session, and must still be allowed to manage provider accounts. Anyone else, or the same user after switching tenant,
is refused with
session-mismatch, and the browser lands on Settings, Providers. - The attempt expires ten minutes after it began and works once.
On success the browser lands on the retailer's Connections page with ?connected=<shop domain>. On failure it lands on
the same page (or Settings, Providers when the attempt was not recognised or the session did not match) with
?error=<code>:
error |
Meaning |
|---|---|
invalid-signature |
Shopify's redirect could not be verified. Start again |
unknown-state |
The attempt is unknown or already used. Start again |
expired-state |
The ten minutes ran out. Start again |
session-mismatch |
A different user or session finished it |
shop-mismatch |
Shopify returned a different shop than the one entered |
shop-connected-elsewhere |
The shop is already connected to another workspace or retailer |
token-exchange-failed |
Shopify did not issue an access token |
retailer-has-shop |
The retailer already has a shop. There is no disconnect operation; uninstall the app in Shopify first, which disconnects the account |
retailer-archived |
The retailer is archived |
account-disconnected |
The account was disconnected earlier; starting the install again for the same shop and retailer reconnects it |
label-taken |
Another account in the tenant already uses the shop's name as its label |
unavailable |
The Shopify app is not configured on this server |
What happens after connecting¶
The platform links the shop and starts, in this order:
- Webhooks. It subscribes the shop to these topics:
orders/create,orders/updated,fulfillments/create,refunds/create,products/create,products/updateandapp/uninstalled. Each delivery is verified with an HMAC signature before anything is read. The platform acts on order and product topics and onapp/uninstalled; it acknowledges the others without changing anything today. - An order import of the shop's history.
- A product import of its catalogue.
Webhooks come first so an order placed during the import cannot fall between the two. Placement is idempotent, so overlap is harmless. If the process stops midway, a reconciler resumes the same runs.
Check progress:
query ProviderAccounts {
providerAccounts {
id
provider
label
externalIdentifier
status
retailerId
webhooks {
registered
expected
at
}
latestImportRuns {
id
kind
status
imported
skipped
reason
}
}
}
If an import failed, or webhooks are not all registered, retry from the account:
mutation RetryShopifyImport($accountId: ID!, $kind: String!) {
retryShopifyImport(accountId: $accountId, kind: $kind) {
id
status
}
}
mutation RegisterShopifyWebhooks($accountId: ID!) {
registerShopifyWebhooks(accountId: $accountId) {
id
webhooks {
registered
expected
}
}
}
kind is orders or products.
Imported orders and products appear in the same lists as manually entered ones.
Shipping rates at checkout¶
A retailer with shipping rate settings can register the platform as a carrier service on the shop:
mutation RegisterShippingCarrier($retailerId: ID!) {
registerShippingCarrier(retailerId: $retailerId) {
carrier {
registered
at
callbackUrl
tokenTail
}
}
}
Registration replaces the platform's carrier service on the shop with one whose callback URL carries a fresh secret
token; only a hash and a masked tail (tokenTail) are stored. rotateShippingCarrierToken(retailerId) is the same
operation again. The web app drives both from a retailer's Shipping, Carrier tab.
Notes:
- Carrier registration needs the
read_shippingandwrite_shippingaccess scopes. A shop installed before those scopes were requested must re-authorise: begin an install again for the same shop and approve "Update data access". Until then, registration answersSCOPE_MISSING. - Registration without shipping settings answers
NOT_FOUND. Set the settings up first. - The callback Shopify calls always answers 200, with an empty list of rates when it cannot quote, because Shopify treats any other status as a broken carrier service.
- Registration failures use
SHOP_NOT_CONNECTED,SHOPIFY_API_FAILED,SHOPIFY_RESPONSE_INVALIDandSHOPIFY_UNAVAILABLE.SHOPIFY_API_FAILEDis worth retrying;SCOPE_MISSINGneeds the re-authorisation above.
Access scopes¶
The app asks Shopify for: read_orders, read_fulfillments, read_customers, read_products, read_inventory,
read_shipping and write_shipping.
Checkout extension¶
The platform ships Shopify checkout UI extensions that show a shopper, on the thank-you page, the order status page and,
where Shopify allows it, in checkout itself, whether their order qualifies for a refund and roughly how much. They call
the Checkout API. Each extension needs one merchant setting, api_url, the API's public base URL;
until it is set the block renders nothing.
Uninstall¶
When the merchant uninstalls the app, Shopify sends app/uninstalled and the platform disconnects the account. This is
the only way to disconnect a shop. To connect it again, run the install again for the same shop and retailer.