Create a transaction

Records a new inventory transaction.

Required fields by type: Stock In/Out → to_location_id (and optional partner_id/tx_time); Move Stock → both from_location_id and to_location_id (and optional tx_time); Adjust Stock → to_location_id. partner_id is rejected on Move Stock and Adjust Stock; tx_time is rejected on Adjust Stock.

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.
The transaction’s effect on the to_location quota may also trigger 402 (plan limit).

POSThttps://rest.boxhero-app.com/v1/transactions

Authorizations

Authorizationstringrequired

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

Request body

typestringrequired

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).

Possible valuesinoutmoveadjust

tx_timestringdate-time

Effective time of the transaction (ISO 8601 datetime string). Defaults to now. Not allowed on Adjust Stock — the server rejects the request if it is set.

from_location_idintegerminimum 0, maximum 2147483647

Source location. Required on Move Stock and rejected on every other transaction type.

to_location_idintegerminimum 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_idintegerminimum 0, maximum 2147483647

Partner (supplier on Stock In, customer on Stock Out). Not allowed on Move Stock or Adjust Stock.

memostringmax length 2000

Free-text memo for the transaction.

itemsarray of objectrequired

Line items to record. Must contain at least one entry.

Show properties

item_idintegerminimum 0, maximum 2147483647

Item id. Mutually exclusive with item_sku.

item_skustringmin length 1, max length 255

Item SKU (case-insensitive). Mutually exclusive with item_id.

quantitynumberrequired

Signed line quantity. Positive for Stock In and Move Stock; negative for Stock Out; signed for Adjust Stock.

Responses

201The created transaction’s id.

idintegerminimum 0, maximum 2147483647required

Id of the newly created transaction.

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

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. Pass an X-Correlation-Id request header to thread your trace through to ours.

instancestringrequired

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.

Show properties

patharray of string | numberrequired

messagestringrequired

401Missing or invalid API token.

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

instancestringrequired

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.

Show properties

patharray of string | numberrequired

messagestringrequired

402The team is over its location plan limit — it has more locations than the current plan covers (for example, extra locations kept after a downgrade), so this stock write is blocked. The limit is team-wide, so targeting a different location does not help; upgrade the plan or remove excess locations to continue.

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

instancestringrequired

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.

Show properties

patharray of string | numberrequired

messagestringrequired

403A line quantity has the wrong sign for the transaction type. Body is /errors/invalid-request with code: invalid-quantity-tx-type-in (Stock In and Move Stock need a positive quantity) or invalid-quantity-tx-type-out (Stock Out needs a negative quantity).

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

instancestringrequired

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.

Show properties

patharray of string | numberrequired

messagestringrequired

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

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

instancestringrequired

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.

Show properties

patharray of string | numberrequired

messagestringrequired

Request

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."
  }'

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();

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()

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."
}

Response

{
  "id": 14012345
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-team-mode",
  "title": "This API is only available in Location mode. For Basic or Unit mode, please contact support.",
  "instance": "/transactions"
}

{
  "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/core/usage-limit-exceeded",
  "title": "The team is over its location plan limit — it has more locations than the current plan covers (for example, extra locations kept after a downgrade), so this stock write is blocked. The limit is team-wide, so targeting a different location does not help; upgrade the plan or remove excess locations to continue.",
  "instance": "/transactions"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/core/forbidden",
  "title": "A line quantity has the wrong sign for the transaction type. Body is /errors/invalid-request with code: invalid-quantity-tx-type-in (Stock In and Move Stock need a positive quantity) or invalid-quantity-tx-type-out (Stock Out needs a negative quantity).",
  "instance": "/transactions"
}

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