> 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/zh-cn/developers/api/reference/transactions/create-transaction.md).

# Create a transaction

> Records a new inventory transaction.

Fields by type: Stock In/Out → `to_location_id` (optional `partner_id`/`tx_time`); Move Stock → `from_location_id` and `to_location_id` (optional `tx_time`); Adjust Stock → `to_location_id`. `to_location_id` may be omitted only when the team has exactly one active location, in which case it is filled in automatically. `partner_id` is rejected on Move Stock and Adjust Stock; `tx_time` is rejected on Adjust Stock and cannot be in the future. Each item may appear only once per transaction.

Semantics:

- Adjust Stock: `quantity` is a **relative** signed increment, not an absolute target. `quantity: 50` adds 50 to the current on-hand stock at the location.
- Stock Out: stock is allowed to go negative; the API does not reject out-transactions that exceed the current on-hand quantity.
- A team that is over any plan limit (items, locations, or members) gets `402` on stock writes until it upgrades or reduces usage.

`POST https://rest.boxhero-app.com/v1/transactions`

## 授权

- `Authorization` (string, 必填): `Bearer <token>` 格式的 Bearer 认证请求头，其中 `<token>` 为你的 [API 令牌](https://www.boxhero.io/docs/zh-cn/developers/api/authentication.md)。

## 请求体

- `type` (string, 必填): Transaction type. `"in"` = Stock In (incoming inventory), `"out"` = Stock Out (outgoing inventory), `"move"` = Move Stock (transfer between two locations), `"adjust"` = Adjust Stock (correction at a single location).

  可选值: `in`, `out`, `move`, `adjust`
- `tx_time` (string, date-time): Effective time of the transaction (ISO 8601 datetime string). Defaults to now. Cannot be in the future. Not allowed on Adjust Stock — the server rejects the request if it is set.
- `from_location_id` (integer, minimum 0, maximum 2147483647): Source location. **Required** on Move Stock and rejected on every other transaction type.
- `to_location_id` (integer, minimum 0, maximum 2147483647): Destination location. Required on every transaction type — except when the team has exactly one active location, in which case it is auto-filled. If omitted while the team has two or more active locations the request is rejected.
- `partner_id` (integer, minimum 0, maximum 2147483647): Partner (supplier on Stock In, customer on Stock Out). Not allowed on Move Stock or Adjust Stock.
- `memo` (string, max length 2000): Free-text memo for the transaction.
- `items` (array of object, 必填): Line items to record. Must contain at least one entry.

  - `item_id` (integer, minimum 0, maximum 2147483647): Item id. Mutually exclusive with item_sku.
  - `item_sku` (string, min length 1, max length 255): Item SKU (case-insensitive). Mutually exclusive with item_id.
  - `quantity` (number, 必填): Signed line quantity. Positive for Stock In and Move Stock; negative for Stock Out; signed for Adjust Stock.

## 响应

**201** The created transaction's id.

- `id` (integer, minimum 0, maximum 2147483647, 必填): Id of the newly created transaction.

**400** Request validation failed (unknown item id, location-field rule violation, `partner_id` on Move/Adjust, `tx_time` on Adjust, team not in LOCATION mode, etc.). See the response body for field-level errors.

- `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, 必填)

**402** The team is over one of its plan limits (items, locations, or members). Upgrade the plan or reduce usage to continue.

- `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, 必填)

**403** `/errors/invalid-request` (HTTP 403) from core, distinguished by `code`: `invalid-quantity-tx-type-in`/`invalid-quantity-tx-type-out` when a line `quantity` has the wrong sign (positive for Stock In and Move Stock, negative for Stock Out), `txs-barcode-id-unique-error` when the same item appears on more than one line, `tx-invalid-param-tx-time-is-future` when `tx_time` is in the future, or `tx-modify-too-old-tx-id` when a backdated `tx_time` would require recalculating more than the team's 5,000 most recent transactions.

- `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, 必填)

**413** Request body exceeds the size limit (1 MiB). Returned with type `/errors/invalid-request`.

- `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 POST \
  --url 'https://rest.boxhero-app.com/v1/transactions' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "move",
    "to_location_id": 47043,
    "from_location_id": 47041,
    "items": [
      {
        "item_id": 14290445,
        "quantity": 2
      }
    ],
    "memo": "Restocking the front store from the back warehouse."
  }'
```

**JavaScript**

```javascript
const response = await fetch("https://rest.boxhero-app.com/v1/transactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "move",
    "to_location_id": 47043,
    "from_location_id": 47041,
    "items": [
      {
        "item_id": 14290445,
        "quantity": 2
      }
    ],
    "memo": "Restocking the front store from the back warehouse."
  }),
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://rest.boxhero-app.com/v1/transactions",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "type": "move",
        "to_location_id": 47043,
        "from_location_id": 47041,
        "items": [
            {
                "item_id": 14290445,
                "quantity": 2,
            },
        ],
        "memo": "Restocking the front store from the back warehouse.",
    },
)
data = response.json()
```

**HTTP**

```http
POST /v1/transactions HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "move",
  "to_location_id": 47043,
  "from_location_id": 47041,
  "items": [
    {
      "item_id": 14290445,
      "quantity": 2
    }
  ],
  "memo": "Restocking the front store from the back warehouse."
}
```

响应

**201**

```json
{
  "id": 14012345
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Request validation failed (unknown item id, location-field rule violation, partner_id on Move/Adjust, tx_time on Adjust, team not in LOCATION mode, etc.). See the response body for field-level errors.",
  "instance": "/transactions"
}
```

**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": "/transactions",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}
```

**402**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/core/usage-limit-exceeded",
  "title": "The team is over one of its plan limits (items, locations, or members). Upgrade the plan or reduce usage to continue.",
  "instance": "/transactions"
}
```

**403**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/core/forbidden",
  "title": "/errors/invalid-request (HTTP 403) from core, distinguished by code: invalid-quantity-tx-type-in/invalid-quantity-tx-type-out when a line quantity has the wrong sign (positive for Stock In and Move Stock, negative for Stock Out), txs-barcode-id-unique-error when the same item appears on more than one line, tx-invalid-param-tx-time-is-future when tx_time is in the future, or tx-modify-too-old-tx-id when a backdated tx_time would require recalculating more than the team's 5,000 most recent transactions.",
  "instance": "/transactions",
  "code": "feature-auth-error-example"
}
```

**413**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Request body is too large.",
  "instance": "/transactions"
}
```

**429**

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