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}

การยืนยันสิทธิ์

Authorizationstringจำเป็น

เฮดเดอร์การยืนยันตัวตนแบบ Bearer ในรูปแบบ Bearer <token> โดย <token> คือ โทเค็น API ของคุณ

พารามิเตอร์ของพาธ

return_numberstringจำเป็น

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

การตอบกลับ

200The requested sales return.

itemReturnจำเป็น

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

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Return id.

return_numberstringจำเป็น

Return number.

return_timestringdate-timeจำเป็น

Return date/time.

statusstringจำเป็น

Return status.

ค่าที่เป็นไปได้confirmedin-progressdone

partnerEntitynullableจำเป็น

Customer for the sales return.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Id of the referenced entity.

namestringจำเป็น

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

deletedbooleanจำเป็น

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

orderOrderRefจำเป็น

Reference to the source sales order for a return.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Order id.

order_numberstringจำเป็น

Order number.

total_pricestringจำเป็น

Return total as a decimal string.

currency_codestringnullableจำเป็น

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

memostringจำเป็น

Free-text memo. Empty string when not set.

revisionintegerminimum -9007199254740991, maximum 9007199254740991จำเป็น

Optimistic-concurrency version.

created_byEntityจำเป็น

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.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Id of the referenced entity.

namestringจำเป็น

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

deletedbooleanจำเป็น

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

created_atstringdate-timeจำเป็น

Server-side creation timestamp.

urlstringuriจำเป็น

Web URL to view this return in the BoxHero app.

tagsarray of stringจำเป็น

Read-only tags parsed from the memo.

itemsarray of ReturnLineจำเป็น

Detailed return lines.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Return line id.

rankintegerminimum -9007199254740991, maximum 9007199254740991จำเป็น

Line rank in the return.

order_item_idintegerminimum 0, maximum 2147483647จำเป็น

Source order line id.

itemExtendedItemEntitynullableจำเป็น

Set when the line references a single item.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Item or bundle id.

namestringจำเป็น

Display name.

skustringจำเป็น

SKU. Empty string when unset.

barcodestringจำเป็น

Barcode. Empty string when unset.

deletedbooleanจำเป็น

Whether the underlying item or bundle is deleted.

bundleExtendedItemEntitynullableจำเป็น

Set when the line references a bundle.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Item or bundle id.

namestringจำเป็น

Display name.

skustringจำเป็น

SKU. Empty string when unset.

barcodestringจำเป็น

Barcode. Empty string when unset.

deletedbooleanจำเป็น

Whether the underlying item or bundle is deleted.

pricestringจำเป็น

Unit price as stored on the line.

quantitynumberจำเป็น

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

tax_namestringnullableจำเป็น

Tax name, or null when no tax is applied.

tax_ratestringnullableจำเป็น

Tax rate as a percentage string.

tax_inclusivebooleannullableจำเป็น

Whether the stored line price includes tax.

discount_namestringnullableจำเป็น

Discount name, or null when no discount is applied.

discount_typestringnullableจำเป็น

Discount type. "percent" is a 0-100 percentage; "amount" is an absolute amount.

ค่าที่เป็นไปได้percentamount

discount_valuestringnullableจำเป็น

Discount percentage or absolute amount.

subtotalstringจำเป็น

price * quantity before discount and tax.

discount_amountstringจำเป็น

Discount amount applied to this line.

tax_amountstringจำเป็น

Inclusive plus exclusive tax amount for this line.

totalstringจำเป็น

Final line total after discount and exclusive tax.

tx_itemsarray of FulfillmentTxItemจำเป็น

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

แสดงพร็อพเพอร์ตี

itemExtendedItemEntityจำเป็น

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

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Item or bundle id.

namestringจำเป็น

Display name.

skustringจำเป็น

SKU. Empty string when unset.

barcodestringจำเป็น

Barcode. Empty string when unset.

deletedbooleanจำเป็น

Whether the underlying item or bundle is deleted.

ordered_quantitynumberจำเป็น

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

fulfilled_quantitynumberจำเป็น

Absolute quantity already fulfilled or received for this item.

pending_quantitynumberจำเป็น

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

transactionsarray of OrderTransactionSummaryจำเป็น

Inventory transactions linked to this return.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Location transaction id.

typestringจำเป็น

Fulfillment direction of an order-linked transaction.

ค่าที่เป็นไปได้inout

transaction_timestringdate-timeจำเป็น

Effective transaction time.

to_locationEntityจำเป็น

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Id of the referenced entity.

namestringจำเป็น

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

deletedbooleanจำเป็น

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

count_of_itemsintegerminimum 0, maximum 9007199254740991จำเป็น

total_quantitynumberจำเป็น

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

401Missing or invalid API token.

idstringจำเป็น

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.

typestringจำเป็น

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

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

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.

instancestringจำเป็น

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

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 /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

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

idstringจำเป็น

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.

typestringจำเป็น

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

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestringจำเป็น

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

errorsarray of object

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.

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

429Rate limit exceeded. Check RateLimit, Retry-After, and X-RateLimit-* response headers before retrying.

idstringจำเป็น

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.

typestringจำเป็น

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

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestringจำเป็น

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

errorsarray of object

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.

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

คำขอ

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>

การตอบกลับ

{
  "item": {
    "id": 90301,
    "return_number": "R-1001",
    "return_time": "2026-01-15T09:30:00.000Z",
    "status": "confirmed",
    "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": "19.99",
        "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.00",
        "tax_amount": "0.00",
        "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": "out",
        "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_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/not-found",
  "title": "No return with the given number was found in this team.",
  "instance": "/returns/by-number/R-1001"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/returns/by-number/R-1001",
  "retryAfter": 60
}