Update a transaction

Partially updates an existing transaction.

Only the fields you include are changed; pass items to replace the entire line-item list, or tx_time to change the transaction’s effective time (e.g. correct a shipment date). Provide revision to enforce optimistic concurrency. Type-specific rules from create still apply (tx_time is rejected on Adjust Stock). When to_location_id is omitted, the existing transaction’s to_location is preserved (memo-only / partial updates are supported).

PUThttps://rest.boxhero-app.com/v1/transactions/{tx_id}

Авторизация

Authorizationstringобязательный

Заголовок аутентификации Bearer в формате Bearer <token>, где <token> — ваш API-токен.

Параметры пути

tx_idintegerminimum 0, maximum 2147483647обязательный

Тело запроса

tx_timestringdate-time

New effective time of the transaction (ISO 8601 datetime string). Cannot be in the future. Not allowed on Adjust Stock. Omit to keep the existing transaction time. Moving the time into the past is rejected with tx-modify-too-old-tx-id when more than 5,000 of the team’s transactions would need recalculation.

from_location_idintegerminimum 0, maximum 2147483647

New source location. Only meaningful on Move Stock transactions.

to_location_idintegerminimum 0, maximum 2147483647

New destination location.

partner_idintegerminimum 0, maximum 2147483647, nullable

New counterparty. Pass null to clear an existing partner. Not allowed on Move Stock or Adjust Stock.

memostringmax length 2000

New memo. Pass an empty string to clear.

itemsarray of object

Replacement line items. When provided, the entire item list is replaced; must contain at least one entry.

Показать свойства

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.

quantitynumberобязательный

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

revisionintegerminimum 0, maximum 9007199254740991

Latest revision you have observed. Omit to skip the concurrency check; pass the current value to refuse the update if another writer beat you to it.

Ответы

200The updated transaction’s id.

idintegerminimum 0, maximum 2147483647обязательный

Id of the updated transaction.

400Request validation failed, the type-specific rules were violated, or the team is not in LOCATION mode.

idstringобязательный

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.

typestringобязательный

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

titlestringобязательный

Human-readable summary of the error, in English.

correlationIDstringобязательный

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.

instancestringобязательный

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.

Показать свойства

patharray of string | numberобязательный

messagestringобязательный

401Missing or invalid API token.

idstringобязательный

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.

typestringобязательный

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

titlestringобязательный

Human-readable summary of the error, in English.

correlationIDstringобязательный

instancestringобязательный

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.

Показать свойства

patharray of string | numberобязательный

messagestringобязательный

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), tx-modify-revision-mismatch when the supplied revision is stale (refetch the latest transaction and retry), tx-invalid-param-tx-time-is-future when tx_time is in the future, or tx-modify-too-old-tx-id when the edit would require recalculating more than the team’s 5,000 most recent transactions (editing very old transactions — including moving tx_time far into the past — is rejected for performance).

idstringобязательный

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.

typestringобязательный

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

titlestringобязательный

Human-readable summary of the error, in English.

correlationIDstringобязательный

instancestringобязательный

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.

Показать свойства

patharray of string | numberобязательный

messagestringобязательный

404No transaction with the given id was found in this team, or it was already deleted.

idstringобязательный

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.

typestringобязательный

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

titlestringобязательный

Human-readable summary of the error, in English.

correlationIDstringобязательный

instancestringобязательный

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.

Показать свойства

patharray of string | numberобязательный

messagestringобязательный

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

idstringобязательный

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.

typestringобязательный

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

titlestringобязательный

Human-readable summary of the error, in English.

correlationIDstringобязательный

instancestringобязательный

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.

Показать свойства

patharray of string | numberобязательный

messagestringобязательный

Запрос

curl --request PUT \
  --url 'https://rest.boxhero-app.com/v1/transactions/{tx_id}' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "tx_time": "2026-01-16T11:00:00.000Z",
    "to_location_id": 47043,
    "from_location_id": 47041,
    "partner_id": 431485,
    "items": [
      {
        "item_id": 14290445,
        "quantity": 2
      }
    ],
    "memo": "Updated memo.",
    "revision": 1
  }'

const response = await fetch("https://rest.boxhero-app.com/v1/transactions/{tx_id}", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "tx_time": "2026-01-16T11:00:00.000Z",
    "to_location_id": 47043,
    "from_location_id": 47041,
    "partner_id": 431485,
    "items": [
      {
        "item_id": 14290445,
        "quantity": 2
      }
    ],
    "memo": "Updated memo.",
    "revision": 1
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    "https://rest.boxhero-app.com/v1/transactions/{tx_id}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "tx_time": "2026-01-16T11:00:00.000Z",
        "to_location_id": 47043,
        "from_location_id": 47041,
        "partner_id": 431485,
        "items": [
            {
                "item_id": 14290445,
                "quantity": 2,
            },
        ],
        "memo": "Updated memo.",
        "revision": 1,
    },
)
data = response.json()

PUT /v1/transactions/{tx_id} HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "tx_time": "2026-01-16T11:00:00.000Z",
  "to_location_id": 47043,
  "from_location_id": 47041,
  "partner_id": 431485,
  "items": [
    {
      "item_id": 14290445,
      "quantity": 2
    }
  ],
  "memo": "Updated memo.",
  "revision": 1
}

Ответ

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

{
  "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/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), tx-modify-revision-mismatch when the supplied revision is stale (refetch the latest transaction and retry), tx-invalid-param-tx-time-is-future when tx_time is in the future, or tx-modify-too-old-tx-id when the edit would require recalculating more than the team's 5,000 most recent transactions (editing very old transactions — including moving tx_time far into the past — is rejected for performance).",
  "instance": "/transactions/12345"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/not-found",
  "title": "No transaction with the given id was found in this team, or it was already deleted.",
  "instance": "/transactions/12345"
}

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