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.

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

Otorisasi

Authorizationstringwajib

Header autentikasi Bearer dengan format Bearer <token>, dengan <token> berupa token API Anda.

Body permintaan

typestringwajib

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

Nilai yang mungkininoutmoveadjust

tx_timestringdate-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_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 objectwajib

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

Tampilkan properti

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.

quantitynumberwajib

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

Respons

201The created transaction's id.

idintegerminimum 0, maximum 2147483647wajib

Id of the newly created transaction.

400Request 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.

idstringwajib

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.

typestringwajib

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

Nilai yang mungkin/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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

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.

instancestring

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.

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

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

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

idstringwajib

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.

typestringwajib

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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

instancestring

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.

codestring

errorsarray of object

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

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

idstringwajib

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.

typestringwajib

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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

instancestring

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.

codestring

errorsarray of object

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

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.

idstringwajib

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.

typestringwajib

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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

instancestring

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.

codestring

errorsarray of object

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

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

idstringwajib

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.

typestringwajib

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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

instancestring

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.

codestring

errorsarray of object

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

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

idstringwajib

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.

typestringwajib

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

titlestringwajib

Human-readable summary of the error, in English.

correlationIDstringwajib

instancestring

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.

codestring

errorsarray of object

Tampilkan properti

patharray of string | numberwajib

messagestringwajib

Permintaan

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

Respons

{
  "id": 14012345
}

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

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

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

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

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

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