> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/ko/developers/api/reference/sales-orders/get-sales-order.md).

# Get a sales order

> Returns a sales order by id, with lines, sales-return totals, per-item fulfillment progress, and linked stock transactions.

Use `/v1/sales-orders/by-number/{order_number}` for lookup by order number. Per-line pending quantity is not available because fulfillment transactions are tracked per item.

`GET https://rest.boxhero-app.com/v1/sales-orders/{order_id}`

## 인증

- `Authorization` (string, 필수): `Bearer <token>` 형식의 Bearer 인증 헤더입니다. `<token>`에는 [API 토큰](https://www.boxhero.io/docs/ko/developers/api/authentication.md)을 넣습니다.

## 경로 파라미터

- `order_id` (integer, minimum 0, maximum 2147483647, 필수): Order id. Use `GET /orders/by-number/{order_number}` to look up by order number.

## 응답

**200** The requested sales order.

- `item` (SalesOrder, 필수): A sales order with lines, per-line sales-return totals, per-item fulfillment progress, linked transactions, and custom fields.

  - `id` (integer, minimum 0, maximum 2147483647, 필수): Order id.
  - `order_number` (string, 필수): Order number.
  - `order_time` (string, date-time, 필수): Order date/time.
  - `estimated_time` (string, date-time, nullable, 필수): Estimated fulfillment date/time.
  - `status` (string, 필수): Order status. Purchase and sales orders may also be `draft`. Recording stock through the order's transaction endpoints advances the status automatically: `confirmed` becomes `in-progress` once any quantity is recorded, and `done` once nothing remains. A `done` order is never reverted by such transaction changes; only an explicit status update can change it.

    가능한 값: `draft`, `confirmed`, `in-progress`, `done`
  - `partner` (Entity, nullable, 필수): Supplier for purchase orders or customer for sales orders.

    - `id` (integer, minimum 0, maximum 2147483647, 필수): Id of the referenced entity.
    - `name` (string, 필수): Display name of the entity at the time the transaction was recorded.
    - `deleted` (boolean, 필수): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
  - `total_price` (string, 필수): Cached order total as a decimal string: the sum of the line totals plus any additional costs. Does not equal the sum of `items[].total` when the order carries costs.
  - `currency_code` (string, nullable, 필수): ISO currency code, or null when unset.
  - `memo` (string, 필수): Free-text memo. Empty string when not set.
  - `revision` (integer, minimum -9007199254740991, maximum 9007199254740991, 필수): Optimistic-concurrency version.
  - `created_by` (Entity, 필수): 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.

    - `id` (integer, minimum 0, maximum 2147483647, 필수): Id of the referenced entity.
    - `name` (string, 필수): Display name of the entity at the time the transaction was recorded.
    - `deleted` (boolean, 필수): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
  - `created_at` (string, date-time, 필수): Server-side creation timestamp.
  - `updated_at` (string, date-time, 필수): Last edit timestamp, or creation timestamp when never edited.
  - `url` (string, uri, 필수): Web URL to view this order in the BoxHero app.
  - `tags` (array of string, 필수): Read-only tags parsed from the memo.
  - `custom_fields` (array of object, 필수): Ordered custom field name-value pairs.

    - `name` (string, 필수)
    - `value` (string, 필수)
  - `items` (array of SalesOrderLine, 필수): Detailed order lines, including per-line sales-return totals.

    - `id` (integer, minimum 0, maximum 2147483647, 필수): Order line id.
    - `rank` (integer, minimum -9007199254740991, maximum 9007199254740991, 필수): Line rank in the order.
    - `item` (ExtendedItemEntity, nullable, 필수): Set when the line references a single item.

      - `id` (integer, minimum 0, maximum 2147483647, 필수): Item or bundle id.
      - `name` (string, 필수): Display name.
      - `sku` (string, 필수): SKU. Empty string when unset.
      - `barcode` (string, 필수): Barcode. Empty string when unset.
      - `deleted` (boolean, 필수): Whether the underlying item or bundle is deleted.
    - `bundle` (ExtendedItemEntity, nullable, 필수): Set when the line references a bundle.

      - `id` (integer, minimum 0, maximum 2147483647, 필수): Item or bundle id.
      - `name` (string, 필수): Display name.
      - `sku` (string, 필수): SKU. Empty string when unset.
      - `barcode` (string, 필수): Barcode. Empty string when unset.
      - `deleted` (boolean, 필수): Whether the underlying item or bundle is deleted.
    - `price` (string, 필수): Unit price as stored on the line.
    - `quantity` (number, 필수): Quantity. May include up to four decimal places in core data.
    - `tax_name` (string, nullable, 필수): Tax name, or null when no tax is applied.
    - `tax_rate` (string, nullable, 필수): Tax rate as a percentage string.
    - `tax_inclusive` (boolean, nullable, 필수): Whether the stored line price includes tax.
    - `discount_name` (string, nullable, 필수): Discount name, or null when no discount is applied.
    - `discount_type` (string, nullable, 필수): Discount type. `"percent"` is a 0-100 percentage; `"amount"` is an absolute amount.

      가능한 값: `percent`, `amount`
    - `discount_value` (string, nullable, 필수): Discount percentage or absolute amount.
    - `subtotal` (string, 필수): price \* quantity before discount and tax.
    - `discount_amount` (string, 필수): Discount amount applied to this line.
    - `tax_amount` (string, 필수): Inclusive plus exclusive tax amount for this line.
    - `total` (string, 필수): Final line total after discount and exclusive tax.
    - `return_quantity` (number, 필수): Quantity already returned across this order's sales returns.
    - `return_amount` (string, 필수): Amount already returned across this order's sales returns.
  - `costs` (array of OrderCost, 필수): Additional costs attached to the order, ordered by rank. Included in total_price but not in any items\[\] figure.

    - `name` (string, 필수): Cost name.
    - `amount` (string, 필수): Cost amount. Negative for a deduction such as a prepayment. Additional costs carry no tax or discount, so the amount is the final value.
    - `rank` (integer, minimum -9007199254740991, maximum 9007199254740991, 필수): Cost rank in the order.
  - `tx_items` (array of FulfillmentTxItem, 필수): Per-item fulfillment progress. Bundle lines are exploded and duplicate items are collapsed.

    - `item` (ExtendedItemEntity, 필수): Reference to an item or bundle embedded in order, return, transaction, and bundle component responses.

      - `id` (integer, minimum 0, maximum 2147483647, 필수): Item or bundle id.
      - `name` (string, 필수): Display name.
      - `sku` (string, 필수): SKU. Empty string when unset.
      - `barcode` (string, 필수): Barcode. Empty string when unset.
      - `deleted` (boolean, 필수): Whether the underlying item or bundle is deleted.
    - `ordered_quantity` (number, 필수): Ordered or returned quantity for this item. Bundle lines are exploded into component quantities and duplicate items are collapsed.
    - `fulfilled_quantity` (number, 필수): Absolute quantity already fulfilled or received for this item.
    - `pending_quantity` (number, 필수): Remaining quantity for this item, clamped to zero when over-fulfilled.
  - `transactions` (array of OrderTransactionSummary, 필수): Inventory transactions linked to this order.

    - `id` (integer, minimum 0, maximum 2147483647, 필수): Location transaction id.
    - `type` (string, 필수): Fulfillment direction of an order-linked transaction.

      가능한 값: `in`, `out`
    - `transaction_time` (string, date-time, 필수): Effective transaction time.
    - `to_location` (Entity, 필수): 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.

      - `id` (integer, minimum 0, maximum 2147483647, 필수): Id of the referenced entity.
      - `name` (string, 필수): Display name of the entity at the time the transaction was recorded.
      - `deleted` (boolean, 필수): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
    - `count_of_items` (integer, minimum 0, maximum 9007199254740991, 필수)
    - `total_quantity` (number, 필수): Quantity. May include up to four decimal places in core data.

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

- `id` (string, 필수): 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.
- `type` (string, 필수): 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`
- `title` (string, 필수): Human-readable summary of the error, in English.
- `correlationID` (string, 필수): 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.
- `instance` (string): 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.
- `code` (string): 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`.
- `errors` (array 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`.

  - `path` (array of string | number, 필수)
  - `message` (string, 필수)

**401** Missing, 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).

- `id` (string, 필수): 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.
- `type` (string, 필수): 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`
- `title` (string, 필수): Human-readable summary of the error, in English.
- `correlationID` (string, 필수): 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.
- `instance` (string): 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.
- `code` (string): 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`.
- `errors` (array 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`.

  - `path` (array of string | number, 필수)
  - `message` (string, 필수)

**404** No sales order with the given id or number was found in this team.

- `id` (string, 필수): 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.
- `type` (string, 필수): 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`
- `title` (string, 필수): Human-readable summary of the error, in English.
- `correlationID` (string, 필수): 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.
- `instance` (string): 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.
- `code` (string): 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`.
- `errors` (array 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`.

  - `path` (array of string | number, 필수)
  - `message` (string, 필수)

**429** Rate 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.

- `id` (string, 필수): 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.
- `type` (string, 필수): 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`
- `title` (string, 필수): Human-readable summary of the error, in English.
- `correlationID` (string, 필수): 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.
- `instance` (string): 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.
- `code` (string): 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`.
- `errors` (array 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`.

  - `path` (array of string | number, 필수)
  - `message` (string, 필수)

요청 예시

**cURL**

```bash
curl --request GET \
  --url 'https://rest.boxhero-app.com/v1/sales-orders/{order_id}' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN"
```

**JavaScript**

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

**Python**

```python
import os
import requests

response = requests.get(
    "https://rest.boxhero-app.com/v1/sales-orders/{order_id}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
)
data = response.json()
```

**HTTP**

```http
GET /v1/sales-orders/{order_id} HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
```

응답 예시

**200**

```json
{
  "item": {
    "id": 90201,
    "order_number": "SO-2001",
    "order_time": "2026-01-15T09:30:00.000Z",
    "estimated_time": "2026-01-20T00:00:00.000Z",
    "status": "in-progress",
    "partner": {
      "id": 431488,
      "name": "Northwind Retail",
      "deleted": false
    },
    "total_price": "2187",
    "currency_code": "USD",
    "memo": "",
    "revision": 3,
    "created_by": {
      "id": 1001,
      "name": "John Smith",
      "deleted": false
    },
    "created_at": "2026-01-15T09:30:00.000Z",
    "updated_at": "2026-01-15T09:30:00.000Z",
    "url": "https://app.boxhero-app.com/sales-orders/90201",
    "tags": [
      "wholesale"
    ],
    "custom_fields": [],
    "items": [
      {
        "id": 700201,
        "rank": 0,
        "item": {
          "id": 14290445,
          "name": "Finish Setting Powder",
          "sku": "SKU-12345678",
          "barcode": "2097678335587",
          "deleted": false
        },
        "bundle": null,
        "price": "19.99",
        "quantity": 100,
        "tax_name": null,
        "tax_rate": null,
        "tax_inclusive": null,
        "discount_name": null,
        "discount_type": null,
        "discount_value": null,
        "subtotal": "1999",
        "discount_amount": "0",
        "tax_amount": "0",
        "total": "1999",
        "return_quantity": 5,
        "return_amount": "99.95"
      },
      {
        "id": 700202,
        "rank": 1,
        "item": {
          "id": 14290446,
          "name": "Hydrating Face Toner",
          "sku": "SKU-12345679",
          "barcode": "2097678335588",
          "deleted": false
        },
        "bundle": null,
        "price": "12.5",
        "quantity": 20,
        "tax_name": "Sales Tax",
        "tax_rate": "8",
        "tax_inclusive": false,
        "discount_name": "Volume discount",
        "discount_type": "percent",
        "discount_value": "10",
        "subtotal": "250",
        "discount_amount": "25",
        "tax_amount": "18",
        "total": "243",
        "return_quantity": 0,
        "return_amount": "0"
      }
    ],
    "costs": [
      {
        "name": "Shipping fee",
        "amount": "45.00",
        "rank": 0
      },
      {
        "name": "Prepayment",
        "amount": "-100.00",
        "rank": 1
      }
    ],
    "tx_items": [
      {
        "item": {
          "id": 14290445,
          "name": "Finish Setting Powder",
          "sku": "SKU-12345678",
          "barcode": "2097678335587",
          "deleted": false
        },
        "ordered_quantity": 100,
        "fulfilled_quantity": 60,
        "pending_quantity": 40
      },
      {
        "item": {
          "id": 14290446,
          "name": "Hydrating Face Toner",
          "sku": "SKU-12345679",
          "barcode": "2097678335588",
          "deleted": false
        },
        "ordered_quantity": 20,
        "fulfilled_quantity": 20,
        "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": 2,
        "total_quantity": 80
      }
    ]
  }
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Invalid path parameter, or the team is not in LOCATION mode.",
  "instance": "/sales-orders/12345"
}
```

**401**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "instance": "/sales-orders/12345",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}
```

**404**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/not-found",
  "title": "No sales order with the given id or number was found in this team.",
  "instance": "/sales-orders/12345"
}
```

**429**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/sales-orders/12345",
  "retryAfter": 60
}
```