Orders API

Retrieve orders, update order status, and manage shipments.

Endpoints

GET

/orders

orders:read

Retrieve a paginated list of orders. Supports filtering by status and date range.

GET

/orders/:id

orders:read

Retrieve a single order with all line items and shipping details.

PUT

/orders/:id/status

orders:write

Update the status of an order (e.g., mark as shipped).

POST

/orders/:id/shipment

orders:write

Attach shipment tracking information to an order.

Field Reference

Field	Type	Required	Description
id	string	No	Unique order identifier (read-only)
orderNumber	string	No	Human-readable order number (read-only)
customerId	string	No	Customer ID (absent for guest orders)
status	string	No	PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED
paymentStatus	string	No	pending, paid, refunded, failed
paymentMethod	string	No	Payment method used (e.g. stripe, cod)
total	integer	No	Total amount in cents (read-only)
items	OrderLine[]	No	Array of line items (read-only)
shippingAddress	Address	No	Shipping address object
fulfillmentType	string	No	shipping, pickup, delivery, or digital
createdAt	datetime	No	ISO 8601 timestamp (read-only)
updatedAt	datetime	No	ISO 8601 timestamp (read-only)

Query Parameters (List)

Field	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20, max: 100)

Example

List recent orders

bash

curl "https://api.mercozy.com/api/v1/external/orders?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

Update order status

bash

curl -X PUT "https://api.mercozy.com/api/v1/external/orders/ord_abc123/status" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped"
  }'

Create shipment tracking

bash

curl -X POST "https://api.mercozy.com/api/v1/external/orders/ord_abc123/shipment" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "trackingNumber": "7489236401",
    "trackingUrl": "https://www.fedex.com/track?id=7489236401"
  }'