Connect a Zid store with OAuth

Purpose#

A Zid store is connected through the Delivery Syria app using OAuth: you approve access in Zid, and from then on every eligible Zid order (see the table below) whose shipping method is Delivery Syria becomes a parcel, and the shipment status goes back to Zid.

Who can use it and what you need#

• An active, verified merchant account with an active merchant profile, signed in. The Zid card is on Store integrations, which is closed to merchants created by a delivery company.
• At least one active pickup location, otherwise the platform refuses the connection.
• Wallet balance for orders to become parcels: you can connect with no balance, but the parcel waits for a top-up and is completed by the hourly balance check; if the balance is still insufficient after 24 hours the parcel is cancelled.
• A shipping method named Delivery Syria in Zid: the shipping method name in the order must contain "Delivery Syria", otherwise the order fails, unless the platform administrator allowed all orders.
• The Zid app credentials are set up on the platform by the platform administrator.

Connection steps#

1. Open the Zid card

   In Store integrations press Connect Zid store (or Reconnect with Zid if the store is already connected). A page opens, in English only, titled "Connect your Zid store to Delivery Syria", showing the account the store will be connected to. If your balance is zero it warns that Zid orders will be saved but will not become shipments until you top up the wallet.

2. Press "Connect my store"

   The page sends you to Zid to approve access.

3. Approve in Zid

   After approval the platform stores the tokens encrypted and subscribes to the order events order.create, order.status.update and order.payment_status.update. A "Your store is connected" page appears and returns you to the Zid dashboard after 5 seconds.

4. Choose the delivery company and pickup location

   On the Zid card choose the shipping company and the pickup location, then press the settings save button (labelled in Arabic: "حفظ إعدادات زد"). Until you do, orders fail with a message starting "إعداد المتجر ناقص:" (store setup incomplete); after saving they are processed again automatically.

5. Review the orders

   The card lists the latest Zid orders (the last 8): order number, customer and result. For an order with a parcel it shows its status in the platform, the status it should have in Zid and its current status in Zid, and a button labelled in Arabic «أرسل الحالة لزد الآن» ("send status to Zid now") shows Zid's reply.

123

1. See this store's orders
2. Delivery company for the store's orders
3. Default pickup place

Expected result#

The platform processes Zid events every minute and right after they arrive:

Weight is the sum of the product weights with a minimum of 1 kg. The governorate is detected from the city and address. A failed order has an address-correction field and a retry button, plus a button to retry all failed orders. If the order is cancelled in Zid after the parcel exists, the parcel is not cancelled and a note asks you to cancel it manually.

Status goes to Zid after each change: arrival at the warehouse, transfer or hub ready; delivery courier assigned or delivery rescheduled indelivery; delivered or partially delivered delivered. The platform sends the new status directly; if Zid refuses the jump, it retries step by step (preparing, ready, indelivery, delivered), skipping the steps the order has already reached. Anything else, such as returns, is not sent. A job every 5 minutes checks sent parcels of the last 30 days and resends what differs.

Token health and reconnecting#

Zid sets the token's lifetime (its expiry date is shown on the card), and an hourly job renews it when less than 60 days remain, if a refresh token exists. Under the card you see its state: healthy, renewing, warning (a failed renewal, or it cannot be renewed automatically) or reconnect needed (expired or app removed). In the last case press "Reconnect with Zid". The button labelled in Arabic «جدّد الآن» ("Refresh now") renews manually. Zid has no Delete button: remove the app in the Zid dashboard and, once Zid notifies the platform, the store is marked as uninstalled and later orders fail. The "Connected" badge still stays on the card, so watch the connection health.

Common mistakes#

These messages appear in the language of the interface: in English on the English interface and in Arabic on the Arabic one.

Limits and permissions#

• Zid events are accepted only with a shared secret, in the X-Hook-Secret header or HTTP Basic authentication; otherwise HTTP 401. Tokens are stored encrypted, and a state value tied to your session prevents linking to someone else's account.
• A Zid store is not counted in "Number of connected stores" and is not listed under "Your connected stores".
• Each batch processes up to 50 pending orders (those with fewer than 30 attempts), and the retry button puts a failed order back in the queue and resets the counter.
• Some texts appear in Arabic only, even in the English interface: the order failure reasons on the Zid card and the buttons «حفظ إعدادات زد», «أرسل الحالة لزد الآن» and «جدّد الآن». The connect and confirmation pages are in English only.