Orders Management

This guide explains how to use the Zid MCP tools for managing orders, returns, and related data in your Zid store. Each tool is callable from your MCP environment and supports flexible filtering, localization, and integration into dashboards or workflows.

1. List Orders (`mcp_Zid_ListOrders`)

Purpose:
Retrieve a paginated list of orders from your Zid store, with powerful filtering options.

Use Cases:

Display all recent orders in your admin dashboard.

Filter orders by status (e.g., only show "new" or "delivered" orders).

Search for orders by customer, date, or payment method.

How to Use:
Call this tool with optional parameters to filter and sort the results.

Parameters:

page (number): Page number for pagination (default: 1).

perPage (number): Number of orders per page (default: 10, max: 100).

orderStatus (string): Filter by order status (new, preparing, ready, indelivery, delivered, canceled).

paymentMethod (string): Filter by payment method (zid_cod, zid_bank_transfer, zid_cop, zid_credit_card).

customerId (number): Filter by customer ID.

dateFrom/dateTo (string): Filter by order creation date range (format: YYYY-MM-DD).

sortBy (string): Sort order (asc or desc).

searchTerm (string): Search by order number, customer name, etc.

language (string): Response language (en or ar).

Example Usage:

List all new orders:
mcp_Zid_ListOrders({ orderStatus: "new" })

List orders from a specific date:
mcp_Zid_ListOrders({ dateFrom: "2024-06-01" })

2. Get Order Details (`mcp_Zid_GetOrderDetails`)

Purpose:
Fetch detailed information about a specific order, including items, customer info, shipping, and payment details.

Use Cases:

View all details for a selected order in your admin panel.

Display order summary to customer support agents.

How to Use:
Provide the orderId (number or string) to retrieve the order.

Parameters:

orderId (number or string): The unique ID of the order.

language (string): Response language (en or ar).

Example Usage:

Get details for order #12345:
mcp_Zid_GetOrderDetails({ orderId: 12345 })

3. Update Order Status (`mcp_Zid_action_UpdateOrderStatus`)

Purpose:
Change the status of an order (e.g., mark as "preparing", "ready", "delivered", or "cancelled").

Use Cases:

Move an order to the next stage in your fulfillment workflow.

Cancel an order if requested by the customer.

How to Use:
Provide the orderId and the new orderStatus. Optionally, include tracking info.

Parameters:

orderId (number or string): The unique ID of the order.

orderStatus (string): New status (new, preparing, ready, indelivery, delivered, cancelled).

inventoryAddressId (string, optional): ID of the inventory location (for shipping).

trackingNumber (string, optional): Shipment tracking number.

trackingUrl (string, optional): URL for tracking the shipment.

waybillUrl (string, optional): URL to the waybill document.

language (string): Response language (en or ar).

Example Usage:

Mark order #12345 as delivered:
mcp_Zid_action_UpdateOrderStatus({ orderId: 12345, orderStatus: "delivered" })

Mark as in delivery with tracking:

mcp_Zid_action_UpdateOrderStatus({ orderId: 12345, orderStatus: "indelivery", trackingNumber: "TRACK123", trackingUrl: "https://track.com/TRACK123" })

4. Get Order Credit Notes (`mcp_Zid_GetOrderCreditNotes`)

Purpose:
Retrieve all credit notes (refunds, adjustments) associated with a specific order.

Use Cases:

Display a list of refunds or adjustments for an order.

Audit order financials for discrepancies.

How to Use:
Provide the orderId.

Parameters:

orderId (number or string): The unique ID of the order.

language (string): Response language (en or ar).

Example Usage:

Get credit notes for order #12345:
mcp_Zid_GetOrderCreditNotes({ orderId: 12345 })

5. Get Order Vouchers (`mcp_Zid_GetOrderVouchers`)

Purpose:
List all vouchers (e.g., gift cards, codes) associated with a specific order.

Use Cases:

Show which vouchers were purchased or used in an order.

Help customer support resolve voucher-related issues.

How to Use:
Provide the orderId. Supports pagination.

Parameters:

orderId (string): The unique ID of the order.

page (number): Page number (default: 1).

pageSize (number): Number per page (default: 15, max: 100).

language (string): Response language (en or ar).

Example Usage:

List vouchers for order #12345:
mcp_Zid_GetOrderVouchers({ orderId: "12345" })

6. Get Reverse Order Reasons (`mcp_Zid_GetReverseOrderReasons`)

Purpose:
Retrieve a list of reasons that can be used when creating a reverse order (return or refund).

Use Cases:

Populate a dropdown for customers to select a return reason.

Analyze common reasons for returns.

How to Use:
No parameters required (optional language).

Parameters:

language (string): Response language (en or ar).

Example Usage:

Get all reverse order reasons:
mcp_Zid_GetReverseOrderReasons({})

7. Add Reverse Order Reason (`mcp_Zid_action_AddReverseOrderReason`)

Purpose:
Add a new reason to the list of available reverse order (return/refund) reasons.

Use Cases:

Customize the list of return reasons for your store.

How to Use:
Provide the reason name.

Parameters:

name (string): The reason to add.

language (string): Response language (en or ar).

Example Usage:

Add a new reason:
mcp_Zid_action_AddReverseOrderReason({ name: "Wrong size" })

8. Create Reverse Order (`mcp_Zid_action_CreateReverseOrder`)

Purpose:
Create a reverse order (return or refund) for an existing order.

Use Cases:

Allow customers or staff to initiate a return process.

Track returns and refunds in your system.

How to Use:
Provide order and consignee details, and the reason(s) for the reverse order.

Parameters:

orderId (number): The original order ID.

consigneeName (string): Name of the person receiving the return.

consigneeMobile (string): Mobile number of the consignee.

consigneeCityId (number): City ID for the consignee.

consigneeAddress1 (string): Address line 1.

consigneeAddress2 (string, optional): Address line 2.

inventoryLocationId (string, optional): Inventory location for the return.

reason (string[]): List of reasons for the return.

language (string): Response language (en or ar).

Example Usage:

Create a reverse order:

mcp_Zid_action_CreateReverseOrder({
  orderId: 12345,
  consigneeName: "John Doe",
  consigneeMobile: "5551234567",
  consigneeCityId: 1,
  consigneeAddress1: "123 Main St",
  reason: ["Wrong item sent"]
})

9. Create Reverse Order Waybill (`mcp_Zid_action_CreateReverseOrderWaybill`)

Purpose:
Generate a shipping waybill for a reverse order (to facilitate the return shipment).

Use Cases:

Provide customers with a return shipping label.

Track the return shipment in your system.

How to Use:
Provide the orderId and optionally specify if it’s a standalone Zidship waybill.

Parameters:

orderId (number): The original order ID.

isStandaloneZidshipWaybill (boolean, optional): Whether to create a standalone Zidship waybill (default: true).

language (string): Response language (en or ar).

Example Usage:

Create a waybill for a reverse order:
mcp_Zid_action_CreateReverseOrderWaybill({ orderId: 12345 })

Summary Table

Tool Name	Purpose/Use Case	Key Parameters
List Orders	List/filter/search orders	page, perPage, orderStatus, etc.
Get Order Details	Fetch full details for a specific order	orderId
Update Order Status	Change the status of an order	orderId, orderStatus, tracking info
Get Order Credit Notes	List credit notes (refunds/adjustments) for an order	orderId
Get Order Vouchers	List vouchers associated with an order	orderId, page, pageSize
Get Reverse Order Reasons	List possible reasons for returns	(none required)
Add Reverse Order Reason	Add a new return reason	name
Create Reverse Order	Initiate a return/refund process	orderId, consignee info, reason
Create Reverse Order Waybill	Generate a return shipping label	orderId, isStandaloneZidshipWaybill

Orders Management

1. List Orders (mcp_Zid_ListOrders)#

2. Get Order Details (mcp_Zid_GetOrderDetails)#

3. Update Order Status (mcp_Zid_action_UpdateOrderStatus)#

4. Get Order Credit Notes (mcp_Zid_GetOrderCreditNotes)#

5. Get Order Vouchers (mcp_Zid_GetOrderVouchers)#

6. Get Reverse Order Reasons (mcp_Zid_GetReverseOrderReasons)#

7. Add Reverse Order Reason (mcp_Zid_action_AddReverseOrderReason)#

8. Create Reverse Order (mcp_Zid_action_CreateReverseOrder)#

9. Create Reverse Order Waybill (mcp_Zid_action_CreateReverseOrderWaybill)#

Summary Table#

1. List Orders (`mcp_Zid_ListOrders`)

2. Get Order Details (`mcp_Zid_GetOrderDetails`)

3. Update Order Status (`mcp_Zid_action_UpdateOrderStatus`)

4. Get Order Credit Notes (`mcp_Zid_GetOrderCreditNotes`)

5. Get Order Vouchers (`mcp_Zid_GetOrderVouchers`)

6. Get Reverse Order Reasons (`mcp_Zid_GetReverseOrderReasons`)

7. Add Reverse Order Reason (`mcp_Zid_action_AddReverseOrderReason`)

8. Create Reverse Order (`mcp_Zid_action_CreateReverseOrder`)

9. Create Reverse Order Waybill (`mcp_Zid_action_CreateReverseOrderWaybill`)

Summary Table