Skip to content

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: owner or admin (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 from actableRetailers.
  • 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_REQUEST and 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:

  1. Webhooks. It subscribes the shop to these topics: orders/create, orders/updated, fulfillments/create, refunds/create, products/create, products/update and app/uninstalled. Each delivery is verified with an HMAC signature before anything is read. The platform acts on order and product topics and on app/uninstalled; it acknowledges the others without changing anything today.
  2. An order import of the shop's history.
  3. 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_shipping and write_shipping access 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 answers SCOPE_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_INVALID and SHOPIFY_UNAVAILABLE. SHOPIFY_API_FAILED is worth retrying; SCOPE_MISSING needs 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.