Create a sales return
Creates a sales return for a sales order.
Set finalize_immediately with location_id to receive all returned quantities immediately — the location must be covered by the team’s plan or the request fails with 402. return_number may only contain letters, numbers, hyphens, underscores, and whitespace; auto-generated when omitted.
https://rest.boxhero-app.com/v1/returnsBearer <token> 格式的 Bearer 认证请求头，其中 <token> 为你的 API 令牌。
Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create.
ISO 8601 timestamp or millisecond epoch.
Source sales order id. Mutually exclusive with order_number.
Source sales order number. Mutually exclusive with order_id.
Latest observed source order revision.
显示属性
Source sales order line id. Identifies the line being returned — return lines are matched to source lines by this id (there is no separate return line id to send).
Quantity. May include up to four decimal places in core data.
Receive all returned quantities immediately and mark the return done.
Required when finalize_immediately is true.
201The created return’s id.
Created return id.
400Request validation failed or core rejected the return.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
401Missing or invalid API token.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
402The team is over its location plan limit — it has more locations than the current plan covers (for example, extra locations kept after a downgrade), so the finalize_immediately stock write is blocked. The limit is team-wide, so targeting a different location does not help; upgrade the plan or remove excess locations to continue.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
404No source order with the given id was found in this team.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
422Returns are only supported for sales orders.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
429Rate limit exceeded. Check RateLimit, Retry-After, and X-RateLimit-* response headers before retrying.
Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.
Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.
可选值/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled
Human-readable summary of the error, in English.
Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.
Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.
Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.
Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.
显示属性
请求
curl --request POST \ --url 'https://rest.boxhero-app.com/v1/returns' \ --header "Authorization: Bearer $BOXHERO_API_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "return_number": "R-1001", "order_number": "SO-2001", "return_time": "2026-01-15T09:30:00.000Z", "memo": "Damaged on arrival", "items": [ { "order_item_id": 700201, "quantity": 5 } ] }'const response = await fetch("https://rest.boxhero-app.com/v1/returns", { method: "POST", headers: { Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ "return_number": "R-1001", "order_number": "SO-2001", "return_time": "2026-01-15T09:30:00.000Z", "memo": "Damaged on arrival", "items": [ { "order_item_id": 700201, "quantity": 5 } ] }),});const data = await response.json();import osimport requests
response = requests.post( "https://rest.boxhero-app.com/v1/returns", headers={ "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"], }, json={ "return_number": "R-1001", "order_number": "SO-2001", "return_time": "2026-01-15T09:30:00.000Z", "memo": "Damaged on arrival", "items": [ { "order_item_id": 700201, "quantity": 5, }, ], },)data = response.json()POST /v1/returns HTTP/1.1Host: rest.boxhero-app.comAuthorization: Bearer <token>Content-Type: application/json
{ "return_number": "R-1001", "order_number": "SO-2001", "return_time": "2026-01-15T09:30:00.000Z", "memo": "Damaged on arrival", "items": [ { "order_item_id": 700201, "quantity": 5 } ]}响应
{ "id": 90301}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/invalid-request", "title": "Request validation failed or core rejected the return.", "instance": "/returns"}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/tokens/required", "title": "Missing API token. Provide a Bearer token in the Authorization header.", "example": "Bearer wqnot0dlysdg5vymubzi4kiv"}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/core/usage-limit-exceeded", "title": "The team is over its location plan limit — it has more locations than the current plan covers (for example, extra locations kept after a downgrade), so the finalize_immediately stock write is blocked. The limit is team-wide, so targeting a different location does not help; upgrade the plan or remove excess locations to continue.", "instance": "/returns"}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/not-found", "title": "No source order with the given id was found in this team.", "instance": "/returns"}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/invalid-request", "title": "Returns are only supported for sales orders.", "instance": "/returns"}{ "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a", "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2", "type": "/errors/too-many-requests", "title": "Too many requests.", "instance": "/returns", "retryAfter": 60}