MMall API Documentation

Changelog

2026-06-03: Added Update product sale status for marketplace operators
2026-06-02: Added Create after-sales request for refunds and returns
2026-05-28: Updated Preview order to return discount and estimated shipping amounts
2026-05-21: Added brand, price range, and sorting filters to Search products
2026-05-10: Added Sign in with SMS code for mobile users

General Information

Item	Value
Base URL	https://api.demo.mmall.example
Content-Type	application/json
Authentication	Bearer Token
Time format	YYYY-MM-DD HH:mm:ss
Money unit
Default pagination	page=1, page_size=20

Common Data Definitions

Currency

Value	Description
	Chinese yuan
	US dollar
	Euro
	Japanese yen

Product

Value	Description
	Draft
	On sale
	Off sale
	Sold out

Order

Value	Description
	Pending payment
	Paid
	Packing
	Shipped
	Completed
	Cancelled
	Closed

Payment

Value	Description
	WeChat Pay
	Alipay
	Account balance
	Bank transfer

Payment

Value	Description
	Unpaid
	Processing
	Paid
	Refunding
	Refunded
	Failed

Delivery

Value	Description
	Standard express
	Same-day delivery
	Store pickup
	Cross-border shipping

After-sales

Value	Description
	Refund only
	Return and refund
	Exchange

After-sales

Value	Description
	Submitted
	Under review
	Approved
	Rejected
	Waiting for return
	Refunding
	Completed
	Cancelled

Coupon

Value	Description
	Available
	Used
	Expired
	Locked

Inventory change

Value	Description
	Purchase inbound
	Order stock lock
	Cancelled order release
	Shipment deduction
	Manual adjustment

Notification

Value	Title	Message template
	Order paid	Your order {order_no} has been paid successfully.
	Order shipped	Your order {order_no} has been shipped. You can view tracking details on the order page.
	Coupon received	You received a {coupon_name}.
	After-sales update	The status of after-sales request {after_sale_no} has changed.
	Back-in-stock notice	The product {product_name} you followed is back in stock.

Users and Sessions

POST

Signs in a user with a phone number and SMS verification code. Returns access and refresh tokens after successful verification.

Request Parameters

Type	Required	Description
string	Yes	Phone number
string	Yes	6-digit SMS verification code
string	No	Sign-in scene. Default is MINI_APP

Field Values

Field	Value	Description
		Mini app sign-in
		Web sign-in

Response Example

{
  : {
    : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.demo",
    : "refresh_20260603103000_8c7a",
    : 7200,
    : {
      : 90001,
      : "13800138000",
      : "Mia Chen",
      : "https://cdn.demo.mmall.example/avatar/u90001.png",
      : "GOLD"
    }
  },
  : ""
}

2. Refresh access

POST

Exchanges a refresh token for a new access token.

Request Parameters

Parameter	Type	Required	Description
	string	Yes	Refresh token

Response Example

{
  : {
    : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.new",
    : 7200
  },
  : ""
}

3. Get current

GET

Returns the profile and membership information of the signed-in user.

Response Example

{
  : {
    : 90001,
    : "13800138000",
    : "Mia Chen",
    : "https://cdn.demo.mmall.example/avatar/u90001.png",
    : "GOLD",
    : 1280,
    : true
  },
  : ""
}

4. Update current

PATCH

Updates the user's nickname, avatar, and birthday.

Request Parameters

Type	Required	Description
string	No	Nickname, up to 32 characters
string	No	Avatar URL
string	No	Birthday in YYYY-MM-DD format

Response Example

{
  : {
    : 90001,
    : "Mia C.",
    : "https://cdn.demo.mmall.example/avatar/u90001-new.png",
    : "1996-08-18"
  },
  : ""
}

5. List shipping

GET

Returns the current user's shipping addresses.

Response Example

{
  : [
    {
      : 3101,
      : "Mia Chen",
      : "13800138000",
      : "Zhejiang",
      : "Hangzhou",
      : "Xihu",
      : "Building 3, 188 Wensan Road, Room 602",
      : "HOME",
      : true
    }
  ],
  : ""
}

6. Create shipping

POST

Creates a new shipping address for the current user.

Request Parameters

Type	Required	Description
string	Yes	Receiver name
string	Yes	Receiver phone number
string	Yes	Province or state
string	Yes	City
string	Yes	District
string	Yes	Detailed address
string	No	Address tag
boolean	No	Whether to set this address as default

Field Values

Field	Value	Description
		Home
		Company
		School

Response Example

{
  : {
    : 3102,
    : false
  },
  : ""
}

7. Update shipping

PATCH

Updates a shipping address.

Request Parameters

Type	Required	Description
number	Yes	Address ID
string	No	Receiver name
string	No	Receiver phone number
string	No	Detailed address
boolean	No	Whether to set this address as default

Response Example

{
  : {
    : 3102,
    : "2026-06-03 10:32:00"
  },
  : ""
}

8. Delete shipping

DELETE

Deletes one of the current user's shipping addresses.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Address ID

Response Example

{
  : {},
  : ""
}

Product Catalog

1. Search

GET

Searches products by keyword, category, brand, price range, and status.

Request Parameters

Type	Required	Description
string	No	Search keyword
number	No	Category ID
number	No	Brand ID
number	No	Minimum price in cents
number	No	Maximum price in cents
string	No	Sort order
number	No	Page number
number	No	Items per page

Field Values

Field	Value	Description
		Recommended order
		Price low to high
		Price high to low
		Sales high to low

Response Example

{
  : {
    : 128,
    : [
      {
        : 501,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : "Aurora",
        : "https://cdn.demo.mmall.example/products/501-cover.jpg",
        : 59900,
        : 79900,
        : "CNY",
        : 8321,
        : "ON_SALE"
      }
    ]
  },
  : ""
}

2. Get product

GET

Returns product details, SKUs, service promises, and images.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Product ID

Response Example

{
  : {
    : 501,
    : "Aurora Wireless Noise-Cancelling Earbuds",
    : "Adaptive active noise cancellation, 8-hour battery life",
    : "Aurora",
    : 59900,
    : "CNY",
    : "ON_SALE",
    : [
      "https://cdn.demo.mmall.example/products/501-1.jpg",
      "https://cdn.demo.mmall.example/products/501-2.jpg"
    ],
    : [
      {
        : 801,
        : "AU-EAR-SPACE-BLK",
        : "Space Black",
        : 59900,
        : 56
      }
    ],
    : [
      "7-day returns",
      "National warranty",
      "Free shipping over 99 CNY"
    ]
  },
  : ""
}

3. List product

GET

Returns the storefront product category tree.

Response Example

{
  : [
    {
      : 10,
      : "Electronics",
      : [
        {
          : 101,
          : "Headphones and Audio"
        },
        {
          : 102,
          : "Smart Wearables"
        }
      ]
    }
  ],
  : ""
}

4. Get home

GET

Returns home page banners, quick entries, and recommended products.

Response Example

{
  : {
    : [
      {
        : "https://cdn.demo.mmall.example/banners/summer-sale.jpg",
        : "CAMPAIGN",
        : 88
      }
    ],
    : [
      {
        : "New Arrivals",
        : "https://cdn.demo.mmall.example/icons/new.png",
        : "/campaigns/new-arrivals"
      }
    ],
    : [
      {
        : 501,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : 59900,
        : "https://cdn.demo.mmall.example/products/501-cover.jpg"
      }
    ]
  },
  : ""
}

5. Get product

GET

Returns sellable stock for each SKU of a product.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Product ID

Response Example

{
  : [
    {
      : 801,
      : "AU-EAR-SPACE-BLK",
      : 56,
      : 12
    },
    {
      : 802,
      : "AU-EAR-MOON-WHT",
      : 34,
      : 5
    }
  ],
  : ""
}

POST

Subscribes the user to a back-in-stock notice for a SKU.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Product ID
	number	Yes	SKU ID

Response Example

{
  : {
    : 7012,
    : 501,
    : 802,
    : "2026-06-03 10:32:00"
  },
  : ""
}

Shopping Cart

1. Get

GET

Returns the current user's cart items, selected state, and invalid items.

Response Example

{
  : {
    : [
      {
        : 12001,
        : 501,
        : 801,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : "Space Black",
        : 59900,
        : 1,
        : true,
        : true
      }
    ],
    : 1,
    : 59900
  },
  : ""
}

2. Add cart

POST

Adds a SKU to the shopping cart.

Request Parameters

Type	Required	Description
number	Yes	Product ID
number	Yes	SKU ID
number	Yes	Quantity

Response Example

{
  : {
    : 12001,
    : 2
  },
  : ""
}

3. Update cart

PATCH

Updates the quantity or selected state of a cart item.

Request Parameters

Type	Required	Description
number	Yes	Cart item ID
number	No	Quantity
boolean	No	Whether the item is selected

Response Example

{
  : {
    : 12001,
    : 1,
    : true
  },
  : ""
}

4. Delete cart

DELETE

Deletes a cart item.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Cart item ID

Response Example

{
  : {},
  : ""
}

5. Select cart

POST

Updates selected state for multiple cart items.

Request Parameters

Parameter	Type	Required	Description
	array	Yes	Cart item ID list
	boolean	Yes	Whether the items are selected

Response Example

{
  : {
    : 2,
    : 129800
  },
  : ""
}

Orders

1. Preview

POST

Calculates product amount, discount amount, shipping fee, and payable amount before creating an order.

Request Parameters

Type	Required	Description
array	No	Required when checking out from cart
array	No	Required for buy-now checkout
number	Yes	Shipping address ID
number	No	Coupon ID
string	No	Delivery type. Default is EXPRESS

Response Example

{
  : {
    : [
      {
        : 801,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : 1,
        : 59900,
        : 59900
      }
    ],
    : 59900,
    : 5000,
    : 0,
    : 54900,
    : "CNY"
  },
  : ""
}

2. Create

POST

Creates an order and locks inventory.

Request Parameters

Type	Required	Description
array	No	Required when checking out from cart
array	No	Required for buy-now checkout
number	Yes	Shipping address ID
number	No	Coupon ID
string	Yes	Delivery type
string	No	Buyer message

Response Example

{
  : {
    : 880001,
    : "MM202606031030008801",
    : "PENDING_PAYMENT",
    : 54900,
    : "2026-06-03 11:00:00"
  },
  : ""
}

3. List

GET

Returns a paginated list of the current user's orders.

Request Parameters

Type	Required	Description
string	No	Order status
number	No	Page number
number	No	Items per page

Response Example

{
  : {
    : 12,
    : [
      {
        : 880001,
        : "MM202606031030008801",
        : "PENDING_PAYMENT",
        : 54900,
        : "2026-06-03 10:30:00",
        : "https://cdn.demo.mmall.example/products/501-cover.jpg",
        : "Aurora Wireless Noise-Cancelling Earbuds and 1 more item"
      }
    ]
  },
  : ""
}

4. Get order

GET

Returns order details, shipping address, payment information, and logistics information.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID

Response Example

{
  : {
    : 880001,
    : "MM202606031030008801",
    : "PAID",
    : "PAID",
    : 54900,
    : {
      : "Mia Chen",
      : "13800138000",
      : "Building 3, 188 Wensan Road, Xihu, Hangzhou"
    },
    : [
      {
        : 801,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : "Space Black",
        : 1,
        : 59900
      }
    ]
  },
  : ""
}

5. Cancel

POST

Cancels an order that has not been shipped.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID
	string	Yes	Cancellation reason

Response Example

{
  : {
    : 880001,
    : "CANCELLED",
    : "2026-06-03 10:45:00"
  },
  : ""
}

6. Confirm

POST

Confirms that the user has received the order and completes it.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID

Response Example

{
  : {
    : 880001,
    : "COMPLETED",
    : "2026-06-06 18:20:00"
  },
  : ""
}

Payments and Invoices

1. Create

POST

Creates a payment for an order and returns payment parameters.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID
	string	Yes	Payment type

Response Example

{
  : {
    : 660001,
    : "PAY202606031032006601",
    : "WECHAT",
    : 54900,
    : {
      : "1780463520",
      : "n0nce20260603",
      : "prepay_id=wx201410272009395522657a690389285100",
      : "RSA",
      : "mock-signature"
    }
  },
  : ""
}

2. Get payment

GET

Returns the current payment status.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Payment ID

Response Example

{
  : {
    : 660001,
    : "PAY202606031032006601",
    : "PAID",
    : "2026-06-03 10:33:12"
  },
  : ""
}

3. Request

POST

Requests an electronic invoice for a paid order.

Request Parameters

Type	Required	Description
number	Yes	Order ID
string	Yes	Invoice title
string	No	Tax number
string	Yes	Recipient email address

Response Example

{
  : {
    : 55001,
    : "SUBMITTED",
    : "finance@example.com"
  },
  : ""
}

4. Get invoice

GET

Returns invoice request details and issuing result.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Invoice ID

Response Example

{
  : {
    : 55001,
    : "Hangzhou Mancang Technology Co., Ltd.",
    : 54900,
    : "ISSUED",
    : "https://cdn.demo.mmall.example/invoices/55001.pdf"
  },
  : ""
}

Coupons and Promotions

1. List available

GET

Returns the current user's available, used, and expired coupons.

Request Parameters

Type	Required	Description
string	No	Coupon status
number	No	Page number
number	No	Items per page

Response Example

{
  : {
    : 3,
    : [
      {
        : 41001,
        : "New user 10 off 99",
        : "AVAILABLE",
        : 9900,
        : 1000,
        : "2026-06-30 23:59:59"
      }
    ]
  },
  : ""
}

2. Claim

POST

Claims a coupon for the current user.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Coupon ID

Response Example

{
  : {
    : 41001,
    : "AVAILABLE"
  },
  : ""
}

3. Quote

POST

Calculates available discounts based on SKUs, shipping address, and coupon.

Request Parameters

Type	Required	Description
array	Yes	SKU and quantity list
number	No	Address ID
number	No	Coupon ID

Response Example

{
  : {
    : [
      {
        : 41001,
        : "New user 10 off 99",
        : 1000
      }
    ],
    : 41001,
    : 1000,
    : 0
  },
  : ""
}

After-Sales

1. Create after-sales

POST

Creates a refund, return-and-refund, or exchange request for an order item.

Request Parameters

Type	Required	Description
number	Yes	Order ID
number	Yes	Order item ID
string	Yes	After-sales type
string	Yes	Reason
number	Yes	Requested quantity
array	No	Proof image URL list

Response Example

{
  : {
    : 730001,
    : "AS202606031055007301",
    : "SUBMITTED",
    : "2026-06-03 10:55:00"
  },
  : ""
}

2. List after-sales

GET

Returns a paginated list of the current user's after-sales requests.

Request Parameters

Type	Required	Description
string	No	After-sales status
number	No	Page number
number	No	Items per page

Response Example

{
  : {
    : 2,
    : [
      {
        : 730001,
        : "AS202606031055007301",
        : "RETURN_AND_REFUND",
        : "REVIEWING",
        : 54900,
        : "2026-06-03 10:55:00"
      }
    ]
  },
  : ""
}

3. Get after-sales

GET

Returns after-sales request details, review result, and processing timeline.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	After-sales request ID

Response Example

{
  : {
    : 730001,
    : "AS202606031055007301",
    : "REVIEWING",
    : "RETURN_AND_REFUND",
    : "The left earbud cannot be charged",
    : 54900,
    : [
      {
        : "SUBMITTED",
        : "User submitted after-sales request",
        : "2026-06-03 10:55:00"
      }
    ]
  },
  : ""
}

4. Upload after-sales

POST

Adds proof images to an after-sales request.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	After-sales request ID
	array	Yes	Proof image URL list

Response Example

{
  : {
    : 730001,
    : 3
  },
  : ""
}

5. Cancel after-sales

POST

Cancels an after-sales request that has not been completed.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	After-sales request ID

Response Example

{
  : {
    : 730001,
    : "CANCELLED"
  },
  : ""
}

Notifications

1. List

GET

Returns system and transaction notifications for the current user.

Request Parameters

Type	Required	Description
boolean	No	Whether to return unread notifications only
number	No	Page number
number	No	Items per page

Field Values

Field	Value	Description
		Unread
		Read

Response Example

{
  : {
    : 8,
    : [
      {
        : 99001,
        : "ORDER_SHIPPED",
        : "UNREAD",
        : "Order shipped",
        : "Your order MM202606031030008801 has been shipped. You can view tracking details on the order page.",
        : "2026-06-03 16:20:00"
      }
    ]
  },
  : ""
}

2. Mark notifications as

POST

Marks a batch of notifications as read.

Request Parameters

Parameter	Type	Required	Description
	array	Yes	Notification ID list

Response Example

{
  : {
    : 3
  },
  : ""
}

Admin Operations

1. Get operation

GET

Returns order count, sales amount, after-sales count, and inventory risk overview for operators.

Request Parameters

Parameter	Type	Required	Description
	string	Yes	Start date in YYYY-MM-DD format
	string	Yes	End date in YYYY-MM-DD format

Response Example

{
  : {
    : 328,
    : 18992000,
    : 12,
    : 7,
    : [
      {
        : 501,
        : "Aurora Wireless Noise-Cancelling Earbuds",
        : 86
      }
    ]
  },
  : ""
}

2. List inventory

GET

Returns SKU inventory change records for operators.

Request Parameters

Type	Required	Description
number	No	SKU ID
string	No	Inventory change type
string	No	Start date
string	No	End date
number	No	Page number
number	No	Items per page

Response Example

{
  : {
    : 42,
    : [
      {
        : 180001,
        : 801,
        : "ORDER_LOCK",
        : -1,
        : 57,
        : 56,
        : "MM202606031030008801",
        : "2026-06-03 10:30:05"
      }
    ]
  },
  : ""
}

3. Adjust

POST

Manually adjusts available stock for a SKU.

Request Parameters

Type	Required	Description
number	Yes	SKU ID
number	Yes	Adjustment quantity. Positive values increase stock and negative values decrease stock
string	Yes	Adjustment reason

Response Example

{
  : {
    : 180002,
    : 801,
    : 66
  },
  : ""
}

4. Update product sale

PATCH

Updates whether a product is visible and purchasable in the storefront.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Product ID
	string	Yes	Product status

Response Example

{
  : {
    : 501,
    : "ON_SALE",
    : "2026-06-03 17:10:00"
  },
  : ""
}

5. List order operation

GET

Returns internal operation notes for an order.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID

Response Example

{
  : [
    {
      : 25001,
      : "Customer requested weekend delivery. Warehouse has been notified.",
      : "Operator Zoe",
      : "2026-06-03 11:20:00"
    }
  ],
  : ""
}

6. Create order operation

POST

Adds an internal operation note to an order.

Request Parameters

Parameter	Type	Required	Description
	number	Yes	Order ID
	string	Yes	Note content

Response Example

{
  : {
    : 25002,
    : "2026-06-03 17:20:00"
  },
  : ""
}

MMall API Documentation

Changelog

General Information

Common Data Definitions

Currency

Product status

Order status

Payment type

Payment status

Delivery type

After-sales type

After-sales status

Coupon status

Inventory change type

Notification event

Users and Sessions

1. Sign in with SMS code

Request Parameters

Field Values

Response Example

2. Refresh access token

Request Parameters

Response Example

3. Get current user

Response Example

4. Update current user

Request Parameters

Response Example

5. List shipping addresses

Response Example

6. Create shipping address

Request Parameters

Field Values

Response Example

7. Update shipping address

Request Parameters

Response Example

8. Delete shipping address

Request Parameters

Response Example

Product Catalog

1. Search products

Request Parameters

Field Values

Response Example

2. Get product details

Request Parameters

Response Example

3. List product categories

Response Example

4. Get home recommendations

Response Example

5. Get product stock

Request Parameters

Response Example

6. Subscribe to back-in-stock notice

Request Parameters

Response Example

Shopping Cart

1. Get cart

Response Example

2. Add cart item

Request Parameters

Response Example

3. Update cart item

Request Parameters

Response Example

4. Delete cart item

Request Parameters

Response Example

5. Select cart items

Request Parameters

Response Example

Orders

1. Preview order

Request Parameters

Response Example

2. Create order

Request Parameters

Response Example

Product

Order

Payment

Payment

Delivery

After-sales

After-sales

Coupon

Inventory change

Notification

1. Sign in with SMS

2. Refresh access

3. Get current

4. Update current

5. List shipping

6. Create shipping

7. Update shipping

8. Delete shipping

1. Search

2. Get product

3. List product

4. Get home

5. Get product

6. Subscribe to back-in-stock

1. Get

2. Add cart

3. Update cart

4. Delete cart

5. Select cart

1. Preview

2. Create

3. List

4. Get order

5. Cancel

6. Confirm

1. Create

2. Get payment

3. Request

4. Get invoice

1. List available

2. Claim

3. Quote

1. Create after-sales

2. List after-sales

3. Get after-sales

4. Upload after-sales

5. Cancel after-sales

1. List

2. Mark notifications as

1. Get operation

2. List inventory

3. Adjust