API reference / Inventory

List inventory items with pagination

GET/open/v1/inventoryScope: inventory:read

Service Endpoint Seller token required

Environment	Base URL + Path
Production	`https://open.mallplus.ph/open/v1/inventory`
Sandbox	`https://sandbox.open.mallplus.ph/open/v1/inventory`

Common Signing and Seller Headers

Header	Type	Required	Rules	Description
X-MallPlus-Partner-Id	string	Yes	Issued client ID for the calling app.	Identifies the partner app whose secret signs the request.
X-MallPlus-Timestamp	integer	Yes	Unix timestamp in seconds; default acceptance window is 90 seconds.	Prevents replay outside the allowed signing window.
X-MallPlus-Signature-Version	string	Yes	Use `3` for HMAC v3.	Selects the request signing algorithm.
X-MallPlus-Nonce	string	Yes	32-64 lowercase hexadecimal characters, unique per request.	Replay-protection nonce included in the v3 signing base string.
X-MallPlus-Signature	string	Yes	HMAC-SHA256 over timestamp, client ID, method, path, canonical query, body hash, and nonce.	Cryptographic proof that the request was signed with the app secret.
X-MallPlus-Access-Token	string	Yes	Required when the operation says seller token required.	Seller OAuth access token returned by the authorization flow.
X-MallPlus-Seller-Id	string	Yes	Required when `X-MallPlus-Access-Token` is required.	Seller ID bound to the seller OAuth token.

Parameters

Name	In	Type	Required	Rules	Description
page	query	integer	No	Minimum: 1	1-based page number to return.
limit	query	integer	No	Minimum: 1; Maximum: 100	Maximum number of records to return.
sku	query	string	No	-	Seller SKU used to filter inventory items.
cursor	query	string	No	-	Pagination cursor returned by a previous response page.

Request Body

This operation has no JSON request body.

Response Parameters

Field	Type	Rules	Description
success	boolean	-	Whether the inventory list request succeeded.
data	array<InventoryItem>	-	Inventory items owned by the authenticated seller.
data[]	InventoryItem	No additional properties	Seller-owned inventory item returned by Inventory endpoints.
data[].id	string	-	Inventory item identifier.
data[].sku	string	-	Seller SKU for the inventory item.
data[].quantity	integer	-	Current available inventory quantity.
data[].sellerId	string	-	Seller identifier that owns the inventory item.
data[].title	string	-	Product title associated with the inventory item when available.
data[].reserved_quantity	integer	-	Inventory quantity reserved for open orders.
data[].incoming_quantity	integer	-	Inventory quantity expected from inbound stock.
data[].variantId	string	-	Product variant identifier associated with the inventory item when available.
data[].created_at	string<date-time>	Format: date-time	Inventory item creation timestamp in ISO-8601 format.
data[].updated_at	string<date-time>	Format: date-time	Inventory item update timestamp in ISO-8601 format.
meta	PaginationMeta	-	Pagination metadata for the inventory list.
meta.page	integer	-	1-based page number represented by this response page.
meta.limit	integer	-	Maximum number of records returned in this response page.
meta.total	integer	-	Total number of records matching the request filters.

Error Codes

HTTP Status	Schema	Description
400	ErrorResponse	Validation error, or a missing/malformed required signing header (BAD_REQUEST)
401	ErrorResponse	Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)
403	ErrorResponse	Forbidden — insufficient scope
429	ErrorResponse	The partner or endpoint rate limit has been exceeded
502	ErrorResponse	The upstream commerce service rejected the request or returned an invalid response
503	ErrorResponse	A required platform or upstream dependency is temporarily unavailable
504	ErrorResponse	The upstream commerce service did not respond before the platform timeout

Machine-readable codes are returned in error.code: ACCOUNT_LOCKED, APPROVE_FAILED, APP_LIMIT_REACHED, APP_NOT_FOUND, AUTHORIZATION_CODE_EXPIRED, AUTHORIZATION_REVOKED, AUTH_CODE_EXPIRED, AUTH_CODE_USED, BAD_REQUEST, CANCELLATION_ALREADY_PROCESSED, CANCELLATION_DEADLINE_EXCEEDED, CANCEL_FAILED, CANNOT_DELETE_ACCOUNT_WITH_APPS, CONCURRENT_MODIFICATION, CONFLICT, CREATE_FAILED, DISPUTE_FAILED, DUPLICATE, EMAIL_ALREADY_EXISTS, EMAIL_NOT_VERIFIED, FILE_TOO_LARGE, FORBIDDEN, HMAC_VERSION_DEPRECATED, IDEMPOTENCY_KEY_IN_PROGRESS, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_REUSED, INTERNAL_ERROR, INVALID_AUTHORIZATION_CODE, INVALID_CREDENTIALS, INVALID_DEVELOPER_TYPE, INVALID_FILE_CONTENT, INVALID_FILE_TYPE, INVALID_JSON, INVALID_NONCE, INVALID_PATH, INVALID_PICKUP_DATE, INVALID_REFRESH_TOKEN, INVALID_REQUEST, INVALID_SIGNATURE, INVALID_STATE, INVALID_TRANSITION, INVALID_VERIFICATION_TOKEN, MAINTENANCE, MEMBER_PERMISSION_DENIED, MISSING_NONCE, NONCE_REUSED, NOT_FOUND, NOT_IMPLEMENTED, ORDER_NOT_CANCELLABLE, PAYLOAD_TOO_LARGE, PICKUP_DATES_UNAVAILABLE, PRODUCT_HAS_ACTIVE_ORDERS, PRODUCT_UNDER_REVIEW, PROFILE_ALREADY_SUBMITTED, PROFILE_TYPE_MISMATCH, PROXY_ERROR, RATE_LIMITED, REDIRECT_URL_MISMATCH, REFRESH_TOKEN_EXPIRED, REFRESH_TOKEN_REUSED, REJECT_FAILED, RETURN_ALREADY_PROCESSED, RETURN_DEADLINE_EXCEEDED, RE_AUTHORIZATION_REQUIRED, SANDBOX_LIMIT_REACHED, SELLER_TOKEN_REQUIRED, SERVICE_UNAVAILABLE, SESSION_EXPIRED, SHIPMENT_ALREADY_ARRANGED, SHIPMENT_NOT_ARRANGED, SHIPPING_LABEL_UNAVAILABLE, SHIP_FAILED, SIGNATURE_REPLAYED, SSRF_CHECK_FAILED, TEST_SHOP_LIMIT_REACHED, TIMESTAMP_EXPIRED, TOKEN_REVOKED, TOO_MANY_REQUESTS, UNAUTHORIZED, UPLOAD_ERROR, UPLOAD_NOT_CONFIGURED, UPSTREAM_ERROR, UPSTREAM_TIMEOUT, VALIDATION_ERROR, VERIFICATION_LINK_USED, VERIFICATION_TOKEN_EXPIRED, WEBHOOK_SUBSCRIPTION_EXISTS

Request Example

curl -X GET "https://open.mallplus.ph/open/v1/inventory" \
  -H "X-MallPlus-Partner-Id: mp_partner_123" \
  -H "X-MallPlus-Timestamp: 1786924800" \
  -H "X-MallPlus-Signature-Version: 3" \
  -H "X-MallPlus-Nonce: 4f8b9a0c4d5e6f708192a3b4c5d6e7f8" \
  -H "X-MallPlus-Signature: <hex_hmac_sha256>" \
  -H "X-MallPlus-Access-Token: seller_access_token" \
  -H "X-MallPlus-Seller-Id: seller_123"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "prod_openapi_inventory",
      "sku": "OPENAPI-INVENTORY-SKU",
      "quantity": 8,
      "sellerId": "seller-openapi-response-contract",
      "created_at": "2026-08-25T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1
  }
}