API reference / Jobs

Poll a tenant-scoped asynchronous bulk job (bjob_ + ULID). Required scope is the write scope of the persisted operation (catalog:write, inventory:write, or orders:write).

GET/open/v1/jobs/{jobId}Scope: catalog:write | inventory:write | orders:write (matches the job operation)

Service Endpoint Seller token required

Environment	Base URL + Path
Production	`https://open.mallplus.ph/open/v1/jobs/{jobId}`
Sandbox	`https://sandbox.open.mallplus.ph/open/v1/jobs/{jobId}`

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
jobId	path	string	Yes	-	The asynchronous bulk job ID returned when the bulk operation was accepted.
offset	query	integer	No	Minimum: 0; Default: 0	0-based item offset for this asynchronous job result page.
limit	query	integer	No	Minimum: 1; Maximum: 100; Default: 50	Maximum number of records to return.

Request Body

This operation has no JSON request body.

Response Parameters

Success status: HTTP 200

Field	Type	Rules	Description
success	enum	Allowed: true	Always true on a successful response.
data	object	-	Job status, aggregate summary, and a page of per-item results.
data.job_id	string	-	Job id (bjob_ + ULID).
data.operation	enum	Allowed: product_create, inventory_update, order_ship, order_cancel	The bulk operation this job executes.
data.status	enum	Allowed: pending, processing, completed, partial_success, failed, cancelled	Overall job status.
data.summary	object	-	Aggregate item counts for the whole job (not just the current page).
data.summary.total	integer	-	Total number of items in this summary.
data.summary.succeeded	integer	-	Number of items that completed successfully.
data.summary.failed	integer	-	Number of items that failed.
data.summary.outcome_unknown	integer	-	Number of items whose final outcome is not yet known.
data.items	array<BulkJobItem>	Max items: 100	Page of per-item results for this poll.
data.items[]	BulkJobItem	No additional properties	One item in an asynchronous bulk job poll page.
data.items[].index	integer	Minimum: 0	Zero-based position of the item in the submitted batch.
data.items[].status	enum	Allowed: pending, processing, succeeded, failed, outcome_unknown	Per-item execution status for this page of the job.
data.items[].resource_id	string	-	Created or updated resource id when the item succeeded (e.g. a product id).
data.items[].result	object	-	Optional executor payload for a succeeded item.
data.items[].error	object	No additional properties	Present when the item failed with a structured error.
data.items[].error.code	string	-	Machine-readable error code for the failed item.
data.items[].error.message	string	-	Human-readable error message for the failed item.
data.pagination	object	-	Offset/limit of the items page in this response.
data.pagination.offset	integer	-	0-based item offset for this result page.
data.pagination.limit	integer	Maximum: 100	Maximum number of result items returned in this page.

Error Codes

HTTP Status	Schema	Description
400	PlatformError400Response	Validation error, or a missing/malformed required signing header (BAD_REQUEST)
401	PlatformError401Response	Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)
403	PlatformError403Response	Forbidden — insufficient scope
404	PlatformError404Response	The requested resource does not exist or is not visible to the authenticated seller
429	PlatformError429Response	The partner or endpoint rate limit has been exceeded
503	PlatformError503Response	A required platform or upstream dependency is temporarily unavailable

This operation can return these codes in error.code: VALIDATION_ERROR, NOT_FOUND, FORBIDDEN

Any operation can also return the authentication, signing, scope, rate-limit and system codes listed in the Error code reference.

Request Example

# Sandbox: https://sandbox.open.mallplus.ph/open/v1/jobs/jobId_123
curl -X GET "https://open.mallplus.ph/open/v1/jobs/jobId_123" \
  -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": {
    "job_id": "bjob_01M2GEXAMPLE000000000000",
    "operation": "product_create",
    "status": "completed",
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0,
      "outcome_unknown": 0
    },
    "items": [
      {
        "index": 0,
        "status": "succeeded",
        "resource_id": "prod_01EXAMPLE"
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 50
    }
  }
}