API reference / Returns

Dispute a return request with a reason code and seller evidence attachments

Return dispute filing is available with limited production-readiness confirmation.

POST/open/v1/returns/{id}/disputeScope: orders:write

Service Endpoint Seller token required

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

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 return case ID.

Request Body required

Field	Type	Required	Rules	Description
reasonCode	enum	Yes	Allowed: did_not_receive_return_parcel, received_physical_damage, received_incomplete, received_wrong_product, received_used_product, buyer_claim_incorrect; Min length: 1; Max length: 100	Machine-readable return dispute reason code.
note	string	Yes	Min length: 1; Max length: 2000	Seller-provided note for the dispute.
attachments	array<ReturnDisputeAttachment>	Yes	Min items: 1; Max items: 6	Evidence attachments for the dispute.
attachments[]	ReturnDisputeAttachment	No	No additional properties	Evidence attachment submitted with a return dispute.
attachments[].url	string<uri>	Yes	Format: uri; Max length: 2048; Pattern: ^https://	Public HTTPS URL for this attachment.
attachments[].name	string	Yes	Min length: 1; Max length: 255	Partner-visible name.
attachments[].size	integer	Yes	Minimum: 1	Attachment size in bytes.
attachments[].mime	enum	Yes	Allowed: image/jpeg, image/png, video/mp4, video/quicktime	Attachment MIME type.
attachments[].durationSeconds	number	No	Minimum: 0	Video duration in seconds.

Response Parameters

Field	Type	Rules	Description
success	boolean	-	Whether the return request succeeded.
data	Return	No additional properties	Return case detail.
data.id	string	-	Stable return case identifier.
data.orderId	string	-	Order identifier associated with the return case.
data.status	string	-	Current return workflow status as returned by the upstream return source.
data.reason	string	-	Return reason recorded on the case.
data.items	array<ReturnItem>	-	Line items included in the return.
data.items[]	ReturnItem	No additional properties	A returned line item projected by the public return DTO.
data.refundAmount	integer	-	Integer amount in PHP centavos.
data.sellerId	string	-	Seller identifier that owns the return case. Omitted when upstream data does not expose it.
data.rejection_reason	string	-	Reason recorded when the return is rejected. Omitted unless the return has been rejected.
data.dispute_reason_code	enum	Allowed: did_not_receive_return_parcel, received_physical_damage, received_incomplete, received_wrong_product, received_used_product, buyer_claim_incorrect	Structured dispute reason code. Omitted unless the seller has filed a dispute.
data.dispute_note	string	-	Seller dispute note explaining the dispute. Omitted unless the seller has filed a dispute.
data.dispute_evidence	array<string>	-	HTTPS evidence URLs submitted with a dispute. Omitted when no dispute evidence was supplied.
data.dispute_evidence[]	string	-	HTTPS URL for one dispute evidence attachment.
data.created_at	string<date-time>	Format: date-time	ISO-8601 timestamp when the return case was created.
data.updated_at	string<date-time>	Format: date-time	ISO-8601 timestamp when the return case was last updated.
data.dispute_window_deadline	string<date-time>	Format: date-time	ISO-8601 deadline by which the seller may still dispute the return case. Omitted when no dispute window is modelled.
data.buyer_evidence_urls	array<string>	-	Buyer-submitted evidence URLs. Omitted when the buyer provided no evidence.
data.buyer_evidence_urls[]	string	-	URL for one buyer-submitted evidence attachment.
data.response_window_deadline	string<date-time>	Format: date-time	ISO-8601 seller response-window deadline. Omitted when the Open API return DTO receives no string deadline from upstream.

data.items[]ReturnItem · 3 fields

A returned line item projected by the public return DTO.

Field	Type	Rules	Description
data.items[].itemId	string	-	Line-item identifier from the order being returned.
data.items[].quantity	integer	-	Number of units for this line item included in the return.
data.items[].reason	string	-	Optional item-level return reason supplied for this line item.

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.