API reference / Inventory
Bulk update inventory levels
Bulk inventory updates are available with limited batch confirmation.
Service Endpoint Seller token required
| Environment | Base URL + Path |
|---|---|
| Production | https://open.mallplus.ph/open/v1/inventory/bulk-update |
| Sandbox | https://sandbox.open.mallplus.ph/open/v1/inventory/bulk-update |
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
This operation does not define path or query parameters in OpenAPI.
Request Body required
| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
| items | array<InventoryBulkUpdateItemRequest> | Yes | Min items: 1; Max items: 5000 | Items associated with this request, response, or event. |
| items[] | InventoryBulkUpdateItemRequest | No | No additional properties | An inventory quantity update included in a bulk inventory request. |
| items[].id | string | Yes | Min length: 1 | Unique identifier for this resource. |
| items[].quantity | integer | Yes | Minimum: 0; Maximum: 1000000000 | Quantity of units. |
| items[].expectedQuantity | integer | Yes | Minimum: 0; Maximum: 1000000000 | Required compare-and-swap guard. This item update only applies if current stock matches this value. |
Response Parameters
| Field | Type | Rules | Description |
|---|---|---|---|
| success | boolean | - | Whether the synchronous bulk inventory request completed. |
| data | InventoryBulkUpdateData | No additional properties | Synchronous bulk inventory update results. |
| data.updated | array<InventoryItem> | - | Inventory items successfully updated by the synchronous bulk request. |
| data.updated[] | InventoryItem | No additional properties | Seller-owned inventory item returned by Inventory endpoints. |
| data.updated[].id | string | - | Inventory item identifier. |
| data.updated[].sku | string | - | Seller SKU for the inventory item. |
| data.updated[].quantity | integer | - | Current available inventory quantity. |
| data.updated[].sellerId | string | - | Seller identifier that owns the inventory item. |
| data.updated[].title | string | - | Product title associated with the inventory item when available. |
| data.updated[].reserved_quantity | integer | - | Inventory quantity reserved for open orders. |
| data.updated[].incoming_quantity | integer | - | Inventory quantity expected from inbound stock. |
| data.updated[].variantId | string | - | Product variant identifier associated with the inventory item when available. |
| data.updated[].created_at | string<date-time> | Format: date-time | Inventory item creation timestamp in ISO-8601 format. |
| data.updated[].updated_at | string<date-time> | Format: date-time | Inventory item update timestamp in ISO-8601 format. |
| data.errors | array<InventoryBulkUpdateError> | - | Per-item failures returned by the synchronous bulk request. |
| data.errors[] | InventoryBulkUpdateError | No additional properties | Per-item inventory update failure in a synchronous bulk update response. |
| data.errors[].id | string | - | Inventory item identifier from the failed update request. |
| data.errors[].message | string | - | Failure reason returned for this inventory item update. |
| data.summary | InventoryBulkUpdateSummary | No additional properties | Aggregate result counts for the synchronous bulk request. |
| data.summary.total | integer | - | Number of inventory updates submitted in the request. |
| data.summary.succeeded | integer | - | Number of inventory updates that succeeded. |
| data.summary.failed | integer | - | Number of inventory updates that failed. |
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 |
| 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.