API reference / Fulfillments
Create a fulfillment
Fulfillment creation is available with limited production-readiness confirmation.
Service Endpoint Seller token required
| Environment | Base URL + Path |
|---|---|
| Production | https://open.mallplus.ph/open/v1/fulfillments |
| Sandbox | https://sandbox.open.mallplus.ph/open/v1/fulfillments |
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 |
|---|---|---|---|---|---|
| Idempotency-Key | header | string | Yes | Min length: 1 | Unique key, generated per request, used to safely retry this call. |
Request Body required
| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
| orderId | string | Yes | Min length: 1; Max length: 64 | Order ID associated with this value. |
| items | array<FulfillmentItemRequest> | Yes | Min items: 1; Max items: 100 | Items associated with this request, response, or event. |
| items[] | FulfillmentItemRequest | No | No additional properties | A fulfillment line item and quantity to fulfill. |
| items[].itemId | string | Yes | Max length: 64 | Line item ID. |
| items[].quantity | integer | Yes | Minimum: 1; Maximum: 1000000 | Quantity of units. |
| trackingNumber | string | No | Max length: 120 | Partner-provided tracking number. |
| trackingCompany | string | No | Max length: 80 | Partner-provided tracking company name. |
Response Parameters
| Field | Type | Rules | Description |
|---|---|---|---|
| success | boolean | - | Whether the request completed successfully. |
| data | Fulfillment | No additional properties | Response or event payload for this schema. |
| data.id | string | - | Unique identifier for this resource. |
| data.status | enum | Allowed: pending, shipped, delivered, cancelled | Current status for this resource or workflow. |
| data.orderId | string | - | Order ID associated with this value. |
| data.trackingNumber | string | - | Partner-provided tracking number. |
| data.trackingCompany | string | - | Partner-provided tracking company name. |
| data.created_at | string<date-time> | Format: date-time | Created at as an ISO-8601 timestamp. |
| data.updated_at | string<date-time> | Format: date-time | Updated at as an ISO-8601 timestamp. |
| data.items | array<FulfillmentItem> | - | Items associated with this request, response, or event. |
| data.items[] | FulfillmentItem | No additional properties | A line item included in a fulfillment response. |
| data.metadata | FulfillmentMetadata | No additional properties | Allowlisted partner-visible metadata. |
data.items[]
A line item included in a fulfillment response.
| Field | Type | Rules | Description |
|---|---|---|---|
| data.items[].itemId | string | - | Line item ID. |
| data.items[].quantity | integer | - | Quantity of units. |
data.metadata
Allowlisted partner-visible metadata.
| Field | Type | Rules | Description |
|---|---|---|---|
| data.metadata.tracking_number | string | - | Shipment tracking number. |
| data.metadata.tracking_company | string | - | Shipment tracking company name. |
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 |
| 422 | ErrorResponse | The request is well-formed but cannot be processed in the resource’s current state |
| 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.