Platforms Integrations
Muvx provides a unified delivery integration API designed for E-Commerce Platforms and Marketplaces to connect their merchants' stores to multiple delivery providers.
Overview
Muvx provides a unified delivery integration API designed for E-Commerce Platforms and Marketplaces. It allows platforms like Ustore or custom-built solutions to seamlessly connect their merchants' stores to multiple delivery providers (Destinations) through a single, consistent interface.
By integrating with Muvx, your platform can:
- Authenticate securely using your Platform Access Token (OAuth2)
- Retrieve a list of available delivery providers (Destinations) and the credential fields they require
- Register merchants from your platform into Muvx
- Allow merchants to connect their stores to one or more delivery Destinations
- Receive and manage a unique Merchant Destination Token (API Key) for each merchant–destination connection
- Use the returned tokens for creating and managing shipments, tracking deliveries, and synchronizing fulfillment data between systems
Muvx handles the complexity of integrating with multiple carriers, giving your platform a single API and consistent data structure across all destinations.
The diagram above provides a high-level overview of the integration flow explained in this documentation.
It helps you understand how the Platform, Muvx, and Delivery Providers interact through the main steps, including authentication, merchant registration, and destination creation.
For a high-resolution version, you can download the PDF here.
Online Postman Documentation
To explore and test the Platforms Integration APIs using ready-made Postman requests and environment variables,
please refer to the Muvx Platforms Integrations Postman documentation.
Base Information
| Property | Value |
|---|---|
| Base URL | https://core.muvx.ai/v1 |
| Protocol | HTTPS (all endpoints require TLS 1.2 or higher) |
| Authentication | Bearer token via OAuth2 Client Credentials flow |
| Content Type | application/json |
| Character Encoding | UTF-8 |
| Rate Limits | 1000 requests per minute per Platform |
| Timeouts | 30 seconds request timeout |
Example Request Header
Authorization: Bearer <platform_access_token>
Content-Type: application/json
Accept: application/jsonAuthentication
All API requests must include a valid Platform Access Token. Tokens are issued using the OAuth2 Client Credentials flow.
Before you can request an access token, you need to create a regular Muvx account and contact the Muvx support team to obtain your client_id and client_secret credentials.
POST /oauth2/token
Request
{
"client_id": "ci_123456789",
"client_secret": "cs_123456789"
}Response
{
"access_token": "plf_access_abcd5678",
"token_type": "bearer",
"expires_in": 31536000
}Use the access_token in all subsequent requests as:
Authorization: Bearer <platform_access_token>The token expires after the configured period (31536000 seconds → 365 days). When it expires, request a new one using the same credentials.
Destinations API
List Available Destinations
Retrieve all delivery providers (Destinations) supported by Muvx. Each destination includes its localized names, logos, descriptions, and credential requirements.
GET /platform/destinations
Headers
Authorization: Bearer <platform_access_token>Response
{
"success": true,
"limit": 20,
"next_cursor": null,
"has_more": false
"destinations": [
{
"id": "dst_qd",
"name": "quick delivery",
"name_ar": "كويك ديلفري",
"logo": "https://cdn.muvx.ai/qd.png",
"logo_ar": "https://cdn.muvx.ai/qd_ar.png",
"description": "Urban and on-demand delivery service tailored for ecommerce and local businesses.",
"description_ar": "خدمة توصيل حضرية وسريعة مصممة خصيصًا للتجارة الإلكترونية والأعمال المحلية.",
"credentials_schema": {
"destination_label": {
"title": "Destination Label",
"title_ar": "ملصق الوجهة",
"type": "string"
},
"client_id": {
"title": "Client ID",
"title_ar": "معرّف العميل",
"type": "string"
},
"client_code": {
"title": "Client Code",
"title_ar": "كود العميل",
"type": "string"
},
"service_type": {
"title": "Service Type",
"title_ar": "نوع الخدمة",
"type": "string",
"enum": ["premium", "flexible"]
}
},
"status": "active"
},
{
"id": "dst_jeen",
"name": "Jeen",
"name_ar": "جين",
"logo": "https://cdn.muvx.ai/jeen.png",
"logo_ar": "https://cdn.muvx.ai/jeen_ar.png",
"description": "Jeen is your everyday app! Delivery, car wash subscription, or water delivery.",
"description_ar": "جين هو تطبيقك اليومي! للتوصيل، أو اشتراك غسيل السيارات، أو توصيل المياه، والمزيد!",
"credentials_schema": {
"destination_label": {
"title": "Destination Label",
"title_ar": "ملصق الوجهة",
"type": "string"
},
"merchant_id": {
"title": "Merchant ID",
"title_ar": "معرّف التاجر",
"type": "string"
}
},
"status": "active"
}
]
}Use the credentials_schema to dynamically render input fields when your merchants choose a destination to connect.
The destinations list endpoint uses cursor-based pagination.
Each response includes:
next_cursor→ The value you must pass in the next request.has_more→ A boolean flag indicating whether more pages are available.
Example Request URLs:
First request
GET /platform/destinations
Next request using next_cursor
GET /platform/destinations?limit=20&cursor=3f82a0d9-ff91-4fb3-ae6b-0d48fc93e21b
Merchants API
Each merchant represents a single online store under an E-Commerce Platform or Marketplace. Merchants are created and managed by the platform, and their connections to delivery providers are authenticated using Destination Tokens (API Keys), there is no separate merchant token.
Create a Merchant
Register a new merchant (store) on Muvx. This step must be performed before creating any destination connections.
POST /platform/merchants
Headers
Authorization: Bearer <platform_access_token>Request
{
"external_id": "shop_98765",
"name": "BookPort Store",
"contact": {
"email": "owner@example.com",
"phone": "+965-00000000",
"country": "Kuwait",
"address_line": "40, Abdul Rahman Al Ghafigi Street",
"website": "https://example.com"
}
}Response
{
"success": true,
"id": "mrc_45f9a",
"external_id": "shop_98765",
"name": "BookPort Store",
"status": "active",
"created_at": "2025-10-19T10:30:00Z"
}The external_id is the merchant's unique ID in your platform (e.g., Ustore store ID). This allows Muvx to associate your internal merchant with its Muvx record. The id field is generated by Muvx, while external_id is supplied by the platform during merchant creation.
List All Merchants
GET /platform/merchants
Headers
Authorization: Bearer <platform_access_token>Response
{
"success": true,
"limit": 20,
"next_cursor": null,
"has_more": false
"merchants": [
{
"id": "mrc_45f9a",
"external_id": "shop_98765",
"name": "DailyMart Store",
"status": "active",
"created_at": "2025-10-19T10:30:00Z"
},
{
"id": "mrc_67a8b",
"external_id": "shop_12345",
"name": "BookPort Store",
"status": "disabled",
"created_at": "2025-10-19T10:30:00Z"
}
]
}The merchants list endpoint uses cursor-based pagination.
Each response includes:
next_cursor→ The value you must pass in the next request.has_more→ A boolean flag indicating whether more pages are available.
Example Request URLs:
First request
GET /platform/merchants
Next request using next_cursor
GET /platform/merchants?limit=20&cursor=3f82a0d9-ff91-4fb3-ae6b-0d48fc93e21b
Retrieve Merchant Details (with Destinations)
Retrieve a merchant's profile, including all connected destinations and their tokens.
GET /platform/merchants/{merchant_id}?include=destinations,apikey
Headers
Authorization: Bearer <platform_access_token>Response
{
"success": true,
"id": "mrc_45f9a",
"external_id": "shop_98765",
"name": "BookPort Store",
"status": "active",
"contact": {
"email": "owner@example.com",
"phone": "+965-91-000000",
"country": "Kuwait",
"address_line": "40, Abdul Rahman Al Ghafigi Street",
"website": "https://example.com"
},
"destinations": [
{
"id": "dst_qd",
"name": "quick delivery",
"name_ar": "كويك ديلفري",
"logo": "https://cdn.muvx.ai/qd.png",
"destination_label": "QD DMS",
"api_key": "src_live_abcd7890",
"status": "connected",
"created_at": "2025-10-19T12:00:00Z"
},
{
"id": "dst_jeen",
"name": "Jeen",
"name_ar": "جين",
"logo": "https://cdn.muvx.ai/jeen.png",
"destination_label": "Jeen DMS",
"api_key": "src_live_xyz9876",
"status": "connected",
"created_at": "2025-10-19T12:00:00Z"
}
],
"created_at": "2025-10-19T10:30:00Z",
"updated_at": "2025-10-20T08:45:00Z"
}Use this endpoint to display merchant integrations on your dashboard or settings page. The include=destinations,apikey query parameter expands the merchant object to include all destination details and their API keys. Without this parameter, the response only returns merchant profile data (no destinations). Each api_key is unique to that merchant–destination pair.
Update Merchant
PATCH /platform/merchants/{merchant_id}
Headers
Authorization: Bearer <platform_access_token>Request
{
"name": "BookNest Store",
"contact": {
"email": "new-email@example.com"
}
}Response
{
"success": true,
"id": "mrc_45f9a",
"name": "BookNest Store",
"contact": {
"email": "new-email@example.com",
"phone": "+965-00000000",
"country": "Kuwait",
"address_line": "40, Abdul Rahman Al Ghafigi Street",
"website": "https://example.com"
},
"updated_at": "2025-10-20T09:00:00Z"
}Merchant Destinations API
Create Merchant Destination
When a merchant selects a destination and provides credentials, use this endpoint to create a destination connection. A unique Merchant Destination Token (API Key) will be returned. This API key must be securely stored by your platform, it will be required for all future operations related to that merchant's orders, such as creating and tracking shipments through Muvx.
Important: Before creating a destination, the merchant must first be registered in Muvx using the Create Merchant API. The merchant_id returned from that endpoint is required here.
POST /platform/merchants/{merchant_id}/destinations
Headers
Authorization: Bearer <platform_access_token>Request
{
"id": "dst_qd",
"credentials": {
"destination_label": "QD DMS",
"client_id": "qd_client_id",
"client_code": "secure_code",
"service_type": "premium"
}
}Response
{
"success": true,
"id": "src_123",
"merchant_id": "mrc_45f9a",
"destination_id": "dst_qd",
"destination_name": "quick delivery",
"destination_name_ar": "كويك ديلفري",
"destination_label": "QD DMS",
"api_key": "src_live_abcd7890",
"status": "connected",
"created_at": "2025-10-19T12:00:00Z"
}When this API is called, Muvx automatically validates the submitted destination credentials before establishing the connection. It performs a real-time verification with the selected delivery provider using the provided credential fields (e.g., client_id, client_code, service_type, etc.) to ensure authenticity and connectivity. If the credentials are valid, the destination connection will be created and activated immediately. If any credential is invalid, missing, or rejected by the provider, Muvx returns a detailed error response indicating which field failed validation or why the connection could not be established.
Next Steps
Up to this point, the integration flow between Muvx and your platform has been covered. You have seen how to:
- Authenticate using Platform Access Tokens
- Retrieve available delivery destinations and their credential requirements
- Register merchants on Muvx
- List and retrieve merchant details
- Update merchant information
- Connect merchants to delivery providers and obtain API keys
- View destination connections and their status
Once you have completed the integration setup and obtained the Merchant Destination Token (API Key), you can proceed with order management operations. For detailed information on managing orders, including:
- Creating shipments and orders
- Checking order status and tracking deliveries
- Triggering pickup requests
- Cancel or update existing orders
- And more
Please refer to the Muvx Order Management documentation.