Connect Shopify

Catalogue: Shopify into Gumza

Go to Catalog → Integrations in the Gumza dashboard. If the tab reports that Shopify is not configured, the deployment has no Shopify app credentials and your operator needs to add them first.

1. Start the install

   Enter your shop domain in the form your-store.myshopify.com. Your custom storefront domain will not work — the Admin API only answers to the myshopify host, and we reject anything else outright.

   You are redirected to Shopify to approve the scopes. By default that is read_products and read_inventory. If your operator has also enabled stock write-back, the install asks for write_inventory — stores connected before that was turned on must reconnect to grant it.

2. Choose what to import

   After approval you land back on the Integrations tab with a preview of what would come across. You can import every collection, or pick specific ones — useful when your Shopify catalogue is much wider than what you want to sell over chat.

3. Run the import

   The import runs as a background job, not inside the request, so a large catalogue does not time out. The page polls for progress and reports what was created, updated and skipped.

4. Leave it running

   Gumza registers product webhooks with your shop at install time, so later edits in Shopify — a price change, a new variant, an item archived — flow through without a re-import.

• POST/api/v1/admin/catalog/integrations/shopify/installBegin the OAuth install for a shop domain
• GET/api/v1/admin/catalog/integrations/shopify/previewPreview what an import would bring across
• GET/api/v1/admin/catalog/integrations/shopify/collectionsList collections you can filter the import by
• PATCH/api/v1/admin/catalog/integrations/shopify/settingsSet the collection filter and stock write-back
• POST/api/v1/admin/catalog/integrations/shopify/syncEnqueue an import
• GET/api/v1/admin/catalog/integrations/shopify/syncPoll import progress
• DELETE/api/v1/admin/catalog/integrations/:idDisconnect and stop receiving product webhooks

Orders: Shopify into Dispatch

The Dispatch install asks Shopify for read_orders, read_customers and read_shipping. Once connected, each order webhook is translated into a delivery: the shipping address becomes the dropoff, the customer name and phone come from the shipping address with the customer record as fallback, and the order total becomes the amount.

Deliveries created this way carry source: "shopify", so they are easy to tell apart from API pushes and CSV imports in the orders list and in reports.

• POST/api/v1/integrations/shopify/installBegin the OAuth install for a merchant
• GET/api/v1/integrations/shopify/merchants/:merchantIdRead the integration status for a merchant
• DELETE/api/v1/integrations/shopify/:integrationIdDisconnect the shop

How the install is secured

Worth knowing if you are reviewing this integration rather than just using it.

• The shop domain is validated against an anchored .myshopify.com pattern before it is ever used. It reaches both a server-side fetch and a browser redirect, so an unvalidated value would be an SSRF primitive and an open redirect at once.
• The OAuth callback carries no session. It is authorised by Shopify's query-string HMAC plus our own signed state token, checked together.
• Every inbound webhook is HMAC-verified against the raw request body before a single field is read.
• Product webhooks are addressed per store, and the shop domain in the payload is checked against the one recorded for that store — so a valid signature from one shop cannot write into another store's catalogue.
• Shopify access tokens are encrypted at rest. Disconnecting deletes them and unsubscribes the webhooks.
• The three mandatory GDPR webhooks — customer data request, customer redact, shop redact — are implemented and verified the same way.

# Gumza — product and lifecycle webhooks
POST https://gumza.ke/api/v1/integrations/shopify/webhooks/<tenantId>
POST https://gumza.ke/api/v1/integrations/shopify/webhooks/app/uninstalled
POST https://gumza.ke/api/v1/integrations/shopify/webhooks/gdpr/customers-data-request
POST https://gumza.ke/api/v1/integrations/shopify/webhooks/gdpr/customers-redact
POST https://gumza.ke/api/v1/integrations/shopify/webhooks/gdpr/shop-redact

# Dispatch — order webhooks
POST https://api.dispatch.gumza.ke/api/v1/integrations/shopify/webhooks/<merchantId>
POST https://api.dispatch.gumza.ke/api/v1/integrations/shopify/webhooks/uninstalled

These are registered for you during the install. You should never have to enter them by hand in the Shopify admin.

If you would rather not use the app

Any platform that can make an HTTP request can push deliveries directly — WooCommerce, a custom storefront, a spreadsheet macro, an internal ERP. Use a Shopify Flow action, a webhook, or your own backend, and call the delivery API with the order details. You get the same idempotency guarantees and the same status webhooks back.