Get a sales return by return number

Looks up a sales return by return number and returns the same payload as GET /returns/{return_id}.

Whitespace is ignored and letters are uppercased.

GEThttps://rest.boxhero-app.com/v1/returns/by-number/{return_number}

Authorizations

Authorizationstringrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API token.

Path parameters

return_numberstringrequired

Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores.

Responses

200The requested sales return.

itemReturnrequired

A sales return with lines, per-item receiving progress, and linked transactions.

Show properties

idintegerminimum 0, maximum 2147483647required

Return id.

return_numberstringrequired

Return number.

return_timestringdate-timerequired

Return date/time.

statusstringrequired

Return status. Recording stock through the return's transaction endpoints advances the status automatically: confirmed becomes in-progress once any quantity is received, and done once nothing remains. A done return is never reverted by such transaction changes.

Possible valuesconfirmedin-progressdone

partnerEntitynullablerequired

Customer for the sales return.

Show properties

idintegerminimum 0, maximum 2147483647required

Id of the referenced entity.

namestringrequired

Display name of the entity at the time the transaction was recorded.

deletedbooleanrequired

true when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.

orderOrderRefrequired

Reference to the source sales order for a return.

Show properties

idintegerminimum 0, maximum 2147483647required

Order id.

order_numberstringrequired

Order number.

total_pricestringrequired

Return total as a decimal string.

currency_codestringnullablerequired

Source sales order ISO currency code, or null when unset.

memostringrequired

Free-text memo. Empty string when not set.

revisionintegerminimum -9007199254740991, maximum 9007199254740991required

Optimistic-concurrency version.

created_byEntityrequired

Reference to a related entity (location, partner, or user) embedded in a transaction. The snapshot is captured at transaction time and does not update if the source entity is later renamed or removed.

Show properties

idintegerminimum 0, maximum 2147483647required

Id of the referenced entity.

namestringrequired

Display name of the entity at the time the transaction was recorded.

deletedbooleanrequired

true when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.

created_atstringdate-timerequired

Server-side creation timestamp.

urlstringurirequired

Web URL to view this return in the BoxHero app.

tagsarray of stringrequired

Read-only tags parsed from the memo.

itemsarray of ReturnLinerequired

Detailed return lines.

Show properties

idintegerminimum 0, maximum 2147483647required

Return line id.

rankintegerminimum -9007199254740991, maximum 9007199254740991required

Line rank in the return.

order_item_idintegerminimum 0, maximum 2147483647required

Source order line id.

itemExtendedItemEntitynullablerequired

Set when the line references a single item.

Show properties

idintegerminimum 0, maximum 2147483647required

Item or bundle id.

namestringrequired

Display name.

skustringrequired

SKU. Empty string when unset.

barcodestringrequired

Barcode. Empty string when unset.

deletedbooleanrequired

Whether the underlying item or bundle is deleted.

bundleExtendedItemEntitynullablerequired

Set when the line references a bundle.

Show properties

idintegerminimum 0, maximum 2147483647required

Item or bundle id.

namestringrequired

Display name.

skustringrequired

SKU. Empty string when unset.

barcodestringrequired

Barcode. Empty string when unset.

deletedbooleanrequired

Whether the underlying item or bundle is deleted.

pricestringrequired

Returned line amount, not a unit price: the source order line's total (including tax and discount) scaled by returned quantity / ordered quantity. Equal to subtotal and total.

quantitynumberrequired

Quantity. May include up to four decimal places in core data.

tax_namestringnullablerequired

Always null on return lines.

tax_ratestringnullablerequired

Always null on return lines.

tax_inclusivebooleannullablerequired

Always null on return lines.

discount_namestringnullablerequired

Always null on return lines.

discount_typestringnullablerequired

Always null on return lines.

Possible valuespercentamount

discount_valuestringnullablerequired

Always null on return lines.

subtotalstringrequired

Same as price: the returned line amount.

discount_amountstringrequired

Always "0"; any source discount is already reflected in price.

tax_amountstringrequired

Always "0"; any source tax is already reflected in price.

totalstringrequired

Same as price: the returned line amount.

tx_itemsarray of FulfillmentTxItemrequired

Per-item receiving progress. Bundle return lines are exploded and duplicate items are collapsed.

Show properties

itemExtendedItemEntityrequired

Reference to an item or bundle embedded in order, return, transaction, and bundle component responses.

Show properties

idintegerminimum 0, maximum 2147483647required

Item or bundle id.

namestringrequired

Display name.

skustringrequired

SKU. Empty string when unset.

barcodestringrequired

Barcode. Empty string when unset.

deletedbooleanrequired

Whether the underlying item or bundle is deleted.

ordered_quantitynumberrequired

Ordered or returned quantity for this item. Bundle lines are exploded into component quantities and duplicate items are collapsed.

fulfilled_quantitynumberrequired

Absolute quantity already fulfilled or received for this item.

pending_quantitynumberrequired

Remaining quantity for this item, clamped to zero when over-fulfilled.

transactionsarray of OrderTransactionSummaryrequired

Inventory transactions linked to this return.

Show properties

idintegerminimum 0, maximum 2147483647required

Location transaction id.

typestringrequired

Fulfillment direction of an order-linked transaction.

Possible valuesinout

transaction_timestringdate-timerequired

Effective transaction time.

to_locationEntityrequired

Show properties

idintegerminimum 0, maximum 2147483647required

Id of the referenced entity.

namestringrequired

Display name of the entity at the time the transaction was recorded.

deletedbooleanrequired

true when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.

count_of_itemsintegerminimum 0, maximum 9007199254740991required

total_quantitynumberrequired

Quantity. May include up to four decimal places in core data.

400Invalid path parameter, or the team is not in LOCATION mode.

idstringrequired

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.

typestringrequired

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

Possible values/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

titlestringrequired

Human-readable summary of the error, in English.

correlationIDstringrequired

Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. A client-supplied X-Correlation-Id request header (at most 128 chars of A-Z a-z 0-9 . _ : / = -) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated rq_… id.

instancestring

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix. Absent on unknown-path 404 and unexpected 500 responses.

codestring

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.

errorsarray of object

Field-level error details. Present on request-validation /errors/invalid-request (400) responses. Absent on malformed-JSON 400, 413 body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include 403). Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

Show properties

patharray of string | numberrequired

messagestringrequired

401Missing, invalid, or revoked API token. /errors/tokens/required when no Bearer token is sent; /errors/tokens/invalid when the token is unknown or revoked (a revoked token may keep working for up to 60 seconds because validation results are cached).

idstringrequired

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.

typestringrequired

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringrequired

Human-readable summary of the error, in English.

correlationIDstringrequired

instancestring

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix. Absent on unknown-path 404 and unexpected 500 responses.

codestring

errorsarray of object

Show properties

patharray of string | numberrequired

messagestringrequired

404No return with the given number was found in this team.

idstringrequired

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.

typestringrequired

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringrequired

Human-readable summary of the error, in English.

correlationIDstringrequired

instancestring

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix. Absent on unknown-path 404 and unexpected 500 responses.

codestring

errorsarray of object

Show properties

patharray of string | numberrequired

messagestringrequired

429Rate limit exceeded. Limits are per team and shared by all of the team's API tokens: 5 requests per second and 300 requests per minute. The RateLimit and X-RateLimit-* headers reflect the per-minute window; check them and Retry-After before retrying. This status is also returned when the client IP exceeds 30 failed authentication attempts within 60 seconds, even if the token is valid.

idstringrequired

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.

typestringrequired

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringrequired

Human-readable summary of the error, in English.

correlationIDstringrequired

instancestring

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix. Absent on unknown-path 404 and unexpected 500 responses.

codestring

errorsarray of object

Show properties

patharray of string | numberrequired

messagestringrequired

Request

curl --request GET \
  --url 'https://rest.boxhero-app.com/v1/returns/by-number/{return_number}' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN"

const response = await fetch("https://rest.boxhero-app.com/v1/returns/by-number/{return_number}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://rest.boxhero-app.com/v1/returns/by-number/{return_number}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
)
data = response.json()

GET /v1/returns/by-number/{return_number} HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>

Response

{
  "item": {
    "id": 90301,
    "return_number": "R-1001",
    "return_time": "2026-01-15T09:30:00.000Z",
    "status": "done",
    "partner": {
      "id": 431488,
      "name": "Northwind Retail",
      "deleted": false
    },
    "order": {
      "id": 90201,
      "order_number": "SO-2001"
    },
    "total_price": "99.95",
    "currency_code": "USD",
    "memo": "",
    "revision": 3,
    "created_by": {
      "id": 1001,
      "name": "John Smith",
      "deleted": false
    },
    "created_at": "2026-01-15T09:30:00.000Z",
    "url": "https://app.boxhero-app.com/returns/90301",
    "tags": [],
    "items": [
      {
        "id": 700301,
        "rank": 0,
        "order_item_id": 700201,
        "item": {
          "id": 14290445,
          "name": "Finish Setting Powder",
          "sku": "SKU-12345678",
          "barcode": "2097678335587",
          "deleted": false
        },
        "bundle": null,
        "price": "99.95",
        "quantity": 5,
        "tax_name": null,
        "tax_rate": null,
        "tax_inclusive": null,
        "discount_name": null,
        "discount_type": null,
        "discount_value": null,
        "subtotal": "99.95",
        "discount_amount": "0",
        "tax_amount": "0",
        "total": "99.95"
      }
    ],
    "tx_items": [
      {
        "item": {
          "id": 14290445,
          "name": "Finish Setting Powder",
          "sku": "SKU-12345678",
          "barcode": "2097678335587",
          "deleted": false
        },
        "ordered_quantity": 5,
        "fulfilled_quantity": 5,
        "pending_quantity": 0
      }
    ],
    "transactions": [
      {
        "id": 14012345,
        "type": "in",
        "transaction_time": "2026-01-16T11:00:00.000Z",
        "to_location": {
          "id": 47041,
          "name": "Warehouse",
          "deleted": false
        },
        "count_of_items": 1,
        "total_quantity": 5
      }
    ]
  }
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Invalid path parameter, or the team is not in LOCATION mode.",
  "instance": "/returns/by-number/R-1001"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "instance": "/returns/by-number/R-1001",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/not-found",
  "title": "No return with the given number was found in this team.",
  "instance": "/returns/by-number/R-1001"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/returns/by-number/R-1001",
  "retryAfter": 60
}