Shopify Integration — Setup Guide

Connect a Shopify store to AltExpress so orders import automatically, AWBs are generated, and tracking/fulfillment + stock are pushed back to Shopify.

Which auth method do you have?

Shopify has two app styles, and the credentials differ:

Token prefixes: shpat_… = static Admin API token (legacy). A 32-char hex value or an atkn_… value is not a usable static token — that's a Dev Dashboard app, so use Client ID + Client secret instead and AltExpress will mint/refresh the token automatically.

The integration sends the token as X-Shopify-Access-Token. For Dev Dashboard apps it mints a fresh token via the client_credentials grant and refreshes it before the 24h expiry — you only store the Client ID + secret, never a token.

Part 1 — Create the Shopify Custom App (done in Shopify admin)

You must be the store owner (or have the "Develop apps" permission) to do this.

1. In your Shopify admin, go to Settings → Apps and sales channels → Develop apps.

2. If prompted, click Allow custom app development (one-time per store).

3. Click Create an app.

   • App name: e.g. AltExpress Fulfillment
   • App developer: your account
   • App URL / Allowed redirection URL(s): leave blank (or any placeholder). This integration uses Admin API token auth, not OAuth — Shopify's App URL and redirect fields are only used by OAuth/install flows, which we don't use. The only URL that matters is the webhook callback in Part 3.

4. Open the app → Configuration tab → Admin API integration → Configure.

5. Enable these Admin API access scopes (the integration needs all of them):

   Scope	Why
   read_orders, write_orders	import orders; cancel them
   read_products, write_products	import products, match SKUs
   read_inventory, write_inventory	push AltExpress stock to Shopify
   read_locations	resolve the inventory location for stock push
   read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders	create fulfillments / push AWB tracking from your own warehouse

   Minimal set to paste:

   read_orders, write_orders, read_products, write_products,
   read_inventory, write_inventory, read_locations,
   read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders
   

   (Don't bother with read_analytics or the customer_* scopes — unused.)

6. Click Save.

7. Copy the credentials for Part 2:

   • Dev Dashboard app: copy the Client ID and Client secret.
   • Legacy "Develop apps": API credentials → Install app, then reveal the Admin API access token (shpat_…, shown once).
   • In both cases, note the API secret key / Client secret — it's the webhook secret.

Part 2 — Connect the store in AltExpress

1. Go to Admin → Settings → Store Integrations (/admin/store-integration).
2. On the Shopify card, click Add. A blank, disabled Shopify store is created and you land on its Settings page.
3. Fill in Shop domain + one auth method:
   • Shop domain — yourstore.myshopify.com (no https://, no trailing slash)
   • Dev Dashboard app → fill Client ID + Client secret (leave Admin API access token blank). AltExpress mints/refreshes the token automatically.
   • Legacy custom app → paste the Admin API access token (shpat_…) (leave Client ID/secret blank).
   • Webhook secret — the API secret key / Client secret from Part 1
   • Import statuses — which Shopify order statuses to import (default: open)
   • Enabled — turn ON when ready to go live
4. Click Save.
5. Use the page actions to verify the connection (import orders / products, compare stock). If you used a Dev Dashboard app, the first action triggers a token mint — a 401 here means the Client ID/secret or scopes are wrong.

Part 3 — Register webhooks in Shopify (real-time order import)

Real-time import (instead of waiting for the scheduled poll) needs Shopify to notify AltExpress when an order is created/updated.

Callback URL (replace {platformId} with the numeric store id shown in the AltExpress store URL after you saved it):

https://staging.altexpress.ro/api/shopify/webhook/{platformId}

(Use https://myaltexpress.com/... for production once deployed there.)

Recommended webhook topics: Order creation and Order updated (and Order cancelled if you want cancellations mirrored). The endpoint is topic-agnostic — it processes whatever order payload arrives.

Each webhook must be signed with the same API secret key you entered as the Webhook secret. AltExpress verifies the X-Shopify-Hmac-Sha256 signature and rejects anything that doesn't match.

What the integration does once connected

Testing checklist

• Custom app created, scopes set, installed; access token + API secret copied
• Store connected in AltExpress with shop domain + token + webhook secret; Save succeeds
• Import products → SKUs match AltExpress stock
• Import an order → shipment is created
• Generate AWB → fulfillment + tracking appears on the Shopify order
• Adjust stock in AltExpress → Shopify inventory updates
• Webhook: place a test order in Shopify → it imports automatically (check the store's Sync Log)

Troubleshooting

• "Invalid webhook signature" → the Webhook secret in AltExpress must equal the Shopify app's API secret key, and the webhook must be sent by that same app.
• Orders not importing → check Import statuses includes the Shopify order's status; confirm the store is Enabled; check the store's Sync Log.
• 401 / auth errors → the access token is wrong/revoked, or a required scope is missing (re-check Part 1, step 5; reinstall the app if you changed scopes).
• Stock not pushing → confirm read_inventory/write_inventory scopes and that the product SKUs match between Shopify and AltExpress.