> 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/id/developers/api/reference/sales-orders.md).

# Sales orders

> Sales orders for outgoing inventory.

Read endpoints expose line detail, sales-return totals, and per-item fulfillment progress.

## Objek 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, wajib): Order id.
- `order_number` (string, wajib): Order number.
- `order_time` (string, date-time, wajib): Order date/time.
- `estimated_time` (string, date-time, nullable, wajib): Estimated fulfillment date/time.
- `status` (string, wajib): Order status. Purchase and sales orders may also be `draft`.

  Nilai yang mungkin: `draft`, `confirmed`, `in-progress`, `done`
- `partner` (Entity, nullable, wajib): Supplier for purchase orders or customer for sales orders.

  - `id` (integer, minimum 0, maximum 2147483647, wajib): Id of the referenced entity.
  - `name` (string, wajib): Display name of the entity at the time the transaction was recorded.
  - `deleted` (boolean, wajib): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
- `total_price` (string, wajib): 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, wajib): ISO currency code, or null when unset.
- `memo` (string, wajib): Free-text memo. Empty string when not set.
- `revision` (integer, minimum -9007199254740991, maximum 9007199254740991, wajib): Optimistic-concurrency version.
- `created_by` (Entity, wajib): 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, wajib): Id of the referenced entity.
  - `name` (string, wajib): Display name of the entity at the time the transaction was recorded.
  - `deleted` (boolean, wajib): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
- `created_at` (string, date-time, wajib): Server-side creation timestamp.
- `updated_at` (string, date-time, wajib): Last edit timestamp, or creation timestamp when never edited.
- `url` (string, uri, wajib): Web URL to view this order in the BoxHero app.
- `tags` (array of string, wajib): Read-only tags parsed from the memo.
- `custom_fields` (array of object, wajib): Ordered custom field name-value pairs.

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

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

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

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

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

  - `name` (string, wajib): Cost name.
  - `amount` (string, wajib): 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, wajib): Cost rank in the order.
- `tx_items` (array of FulfillmentTxItem, wajib): Per-item fulfillment progress. Bundle lines are exploded and duplicate items are collapsed.

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

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

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

    Nilai yang mungkin: `in`, `out`
  - `transaction_time` (string, date-time, wajib): Effective transaction time.
  - `to_location` (Entity, wajib): 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, wajib): Id of the referenced entity.
    - `name` (string, wajib): Display name of the entity at the time the transaction was recorded.
    - `deleted` (boolean, wajib): `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, wajib)
  - `total_quantity` (number, wajib): Quantity. May include up to four decimal places in core data.

Contoh

```json
{
  "id": 90201,
  "order_number": "SO-2001",
  "order_time": "2026-01-15T09:30:00.000Z",
  "estimated_time": "2026-01-20T00:00:00.000Z",
  "status": "confirmed",
  "partner": {
    "id": 431488,
    "name": "Northwind Retail",
    "deleted": false
  },
  "total_price": "2187.56",
  "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.00",
      "discount_amount": "0.00",
      "tax_amount": "0.00",
      "total": "1999.00",
      "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.50",
      "quantity": 20,
      "tax_name": "Sales Tax",
      "tax_rate": "8.25",
      "tax_inclusive": false,
      "discount_name": "Volume discount",
      "discount_type": "percent",
      "discount_value": "10",
      "subtotal": "250.00",
      "discount_amount": "25.00",
      "tax_amount": "18.56",
      "total": "243.56",
      "return_quantity": 0,
      "return_amount": "0.00"
    }
  ],
  "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": 1,
      "total_quantity": 100
    }
  ]
}
```

## Endpoint

- [List sales orders](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/list-sales-orders) `GET /v1/sales-orders`
- [Create a sales order](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/create-sales-order) `POST /v1/sales-orders`
- [Get a sales order](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/get-sales-order) `GET /v1/sales-orders/{order_id}`
- [Update a sales order](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/update-sales-order) `PUT /v1/sales-orders/{order_id}`
- [Delete a sales order](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/delete-sales-order) `DELETE /v1/sales-orders/{order_id}`
- [Update sales order status](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/update-sales-order-status) `PUT /v1/sales-orders/{order_id}/status`
- [Ship sales order quantities](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/create-sales-order-transaction) `POST /v1/sales-orders/{order_id}/transactions`
- [Ship all remaining sales order quantities](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/complete-sales-order-transactions) `POST /v1/sales-orders/{order_id}/transactions/complete`
- [Get a sales order by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/get-sales-order-by-number) `GET /v1/sales-orders/by-number/{order_number}`
- [Update a sales order by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/update-sales-order-by-number) `PUT /v1/sales-orders/by-number/{order_number}`
- [Delete a sales order by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/delete-sales-order-by-number) `DELETE /v1/sales-orders/by-number/{order_number}`
- [Update sales order status by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/update-sales-order-status-by-number) `PUT /v1/sales-orders/by-number/{order_number}/status`
- [Create sales order fulfillment transaction by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/create-sales-order-transaction-by-number) `POST /v1/sales-orders/by-number/{order_number}/transactions`
- [Complete all remaining sales order fulfillment by order number](https://www.boxhero.io/docs/id/developers/api/reference/sales-orders/complete-sales-order-transactions-by-number) `POST /v1/sales-orders/by-number/{order_number}/transactions/complete`