## 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. Muvx Platform Integration Flow

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](https://sawaai.lon1.digitaloceanspaces.com/bot/1762178314579_Muvx%20Platform%20Flow.pdf). --- ## 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](/documentation/postman-platforms). --- ## 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 ```json Authorization: Bearer Content-Type: application/json Accept: application/json ``` --- ## Authentication 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** ```json { "client_id": "ci_123456789", "client_secret": "cs_123456789" } ``` **Response** ```json { "access_token": "plf_access_abcd5678", "token_type": "bearer", "expires_in": 31536000 } ``` Use the `access_token` in all subsequent requests as: ```json Authorization: Bearer ``` 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** ```json Authorization: Bearer ``` **Response** ```json { "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** ```json Authorization: Bearer ``` **Request** ```json { "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** ```json { "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** ```json Authorization: Bearer ``` **Response** ```json { "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** ```json Authorization: Bearer ``` **Response** ```json { "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** ```json Authorization: Bearer ``` **Request** ```json { "name": "BookNest Store", "contact": { "email": "new-email@example.com" } } ``` **Response** ```json { "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** ```json Authorization: Bearer ``` **Request** ```json { "id": "dst_qd", "credentials": { "destination_label": "QD DMS", "client_id": "qd_client_id", "client_code": "secure_code", "service_type": "premium" } } ``` **Response** ```json { "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](/documentation/api-order-management).

Code	Meaning
`not_found`	Resource does not exist
`validation_error`	Missing or invalid field
`unauthorized`	Invalid/missing token
`duplicate_order`	Duplicate integration_order_id
`invalid_action`	Action not allowed for the current state
`internal_error`	Something went wrong on our side

Common Error Codes