API reference / Returns

List return cases (return_refund / cancellation / failed_delivery) with type + status filters

GET/open/v1/returnsScope: orders:read

Service Endpoint Seller token required

Environment	Base URL + Path
Production	`https://open.mallplus.ph/open/v1/returns`
Sandbox	`https://sandbox.open.mallplus.ph/open/v1/returns`

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
page	query	integer	No	Minimum: 1	1-based page number to return.
limit	query	integer	No	Minimum: 1; Maximum: 100	Maximum number of records to return.
type	query	enum	No	Allowed: return_refund, cancellation, failed_delivery	Return case type to include in the list.
status	query	enum	No	Allowed: pending, approved, disputed, resolved	Return case status to include in the list.
order_id	query	string	No	-	Order ID used to filter related records.
created_before	query	string<date-time>	No	Format: date-time	Return records created before this ISO-8601 timestamp.
cursor	query	string	No	-	Pagination cursor returned by a previous response page.

Request Body

This operation has no JSON request body.

Response Parameters

Field	Type	Rules	Description
success	boolean	-	Whether the return case list request succeeded.
data	array<ReturnCase>	-	Return cases visible to the authenticated seller token.
data[]	ReturnCase	No additional properties	A return case row in the unified after-sales case list.
data[].case_id	string	-	Return case identifier used to fetch or act on the case.
data[].type	enum	Allowed: return_refund, cancellation, failed_delivery	Partner-facing case type for the after-sales flow.
data[].order_id	string	-	Order identifier associated with the case.
data[].status	enum	Allowed: pending, approved, disputed, resolved	Partner-facing case status mapped from the upstream return workflow.
data[].created_at	string<date-time>	Format: date-time	ISO-8601 timestamp when the case was created. Omitted when upstream data does not provide it.
meta	PaginationMeta	-	Response metadata, including pagination when the endpoint returns a list.
meta.page	integer	-	1-based page number represented by this response page.
meta.limit	integer	-	Maximum number of records returned in this response page.
meta.total	integer	-	Total number of records matching the request filters.
note	string	-	Wrapper-level note explaining that cancellation or failed_delivery case lists are empty because those types have no upstream source yet.

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

Request Example

curl -X GET "https://open.mallplus.ph/open/v1/returns" \
  -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": [
    {
      "case_id": "ret_SqS5eJgMmQ67",
      "type": "return_refund",
      "order_id": "ORD-SAMPLE-001",
      "status": "pending",
      "created_at": "2026-08-26T03:21:10.025Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1,
    "total": 1
  }
}