API reference / Fulfillments

Update a fulfillment

Fulfillment updates are available with limited production-readiness confirmation.

PUT/open/v1/fulfillments/{id}Scope: fulfillment:write

Service Endpoint Seller token required

Environment	Base URL + Path
Production	`https://open.mallplus.ph/open/v1/fulfillments/{id}`
Sandbox	`https://sandbox.open.mallplus.ph/open/v1/fulfillments/{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 fulfillment ID.

Request Body required

Field	Type	Required	Rules	Description
status	enum	No	Allowed: pending, shipped, delivered, cancelled	Current status for this resource or workflow.
trackingNumber	string	No	Max length: 120	Partner-provided tracking number.
trackingCompany	string	No	Max length: 80	Partner-provided tracking company name.
expectedStatus	enum	No	Allowed: pending, shipped, delivered, cancelled	Optional optimistic-locking guard. When supplied, the update is rejected with 409 if the fulfillment status changed before the write was applied.

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[]FulfillmentItem · 2 fields

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.metadataFulfillmentMetadata · 2 fields

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
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
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.