API reference / Inventory
Update inventory for a single item
Single inventory updates are available with limited exact-stock confirmation.
Service Endpoint Seller token required
| Environment | Base URL + Path |
|---|---|
| Production | https://open.mallplus.ph/open/v1/inventory/{id} |
| Sandbox | https://sandbox.open.mallplus.ph/open/v1/inventory/{id} |
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 |
|---|---|---|---|---|---|
| id | path | string | Yes | - | The inventory item ID. |
Request Body required
| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
| quantity | integer | Yes | Minimum: 0; Maximum: 1000000000 | Quantity of units. |
| expectedQuantity | integer | Yes | Minimum: 0; Maximum: 1000000000 | Required compare-and-swap guard. The update only applies if current stock matches this value. |
Response Parameters
| Field | Type | Rules | Description |
|---|---|---|---|
| success | boolean | - | Whether the inventory item request succeeded. |
| data | InventoryItem | No additional properties | Updated inventory item data. |
| 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. |
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 |
| 404 | ErrorResponse | The requested resource does not exist or is not visible to the authenticated seller |
| 409 | ErrorResponse | The request conflicts with the current resource state or reuses an idempotency key |
| 413 | ErrorResponse | The request body exceeds the endpoint payload limit |
| 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
Examples
Executable examples are hidden for this endpoint until copy-paste guidance is published.