Zid Integration Guide
Connect your Zid store to ZaLinkAI and enable AI agents to manage products, orders, and customers.
OAuth 2.0 Authentication
Zid uses a 3-legged OAuth 2.0 flow for secure store authorization.
Redirect to Zid
Send the merchant to the Zid authorization URL with your client_id, redirect_uri, and a unique state parameter for CSRF protection.
Merchant Grants Permission
The merchant reviews the requested scopes (products, orders, customers, webhooks, cart) and approves access to their store.
Receive Callback
Zid redirects back to your redirect_uri with an authorization code and the state parameter for verification.
Exchange for Tokens
POST the authorization code to the Zid token endpoint to receive an access_token and refresh_token. Tokens are encrypted and stored securely.
Platform Capabilities
Full overview of what AI agents can do through the Zid integration.
Product Catalog
- Sync all products with Arabic/English names
- Read inventory levels in real-time
- Access product variants, images, and prices
- Category and collection mapping
Order Management
- Retrieve order history and details
- Update order status (pending, shipped, delivered)
- Process refunds and cancellations
- Access order notes and tracking info
Customer Data
- Access customer profiles and segments
- View purchase history per customer
- Customer address and contact info
- RFM segmentation data
Webhooks
- order.created, order.updated events
- product.created, product.deleted events
- customer.created, customer.updated events
- app.uninstalled notification
Cart & Checkout
- Create and modify shopping carts
- Generate secure checkout URLs
- Apply discount codes
- Calculate shipping and VAT
Localization
- SAR and AED currency support
- Arabic and English bilingual data
- Saudi VAT (15%) pre-configured
- ZATCA-compliant tax handling
Supported Currencies
Saudi Riyal
Saudi Arabia
UAE Dirham
United Arab Emirates
Troubleshooting
Common issues and their solutions when integrating with Zid.
invalid_grant
Authorization code has expired or was already used.
Restart the OAuth flow. Codes are single-use and expire after 10 minutes.
token_refresh_failed
Refresh token is invalid or the merchant revoked access.
Prompt the merchant to re-authorize. ZaLinkAI auto-refreshes tokens 30 minutes before expiry.
scope_not_granted
Merchant did not approve all requested permissions.
Check which scopes were granted. Re-request authorization with required scopes only.
webhook_delivery_failed
Your endpoint returned a non-2xx status code.
Ensure your webhook URL is publicly accessible and returns 200. Failed webhooks retry with exponential backoff.