Update a sales return by return number

Looks up a sales return by return number and applies the same partial update as PUT /returns/{return_id}.

Whitespace is ignored and letters are uppercased.

PUThttps://rest.boxhero-app.com/v1/returns/by-number/{return_number}

Авторизация

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

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

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

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

Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores.

Тело запроса

return_numberstring

Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create.

return_timestring | number | string

ISO 8601 timestamp or millisecond epoch.

memostringmax length 2000

statusstring

Return status.

Возможные значенияconfirmedin-progressdone

order_revisionintegerminimum 0, maximum 9007199254740991

Latest observed source order revision when replacing items.

itemsarray of object

Replacement return lines. Omit to preserve the current lines.

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

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

Source sales order line id. Identifies the line being returned — return lines are matched to source lines by this id (there is no separate return line id to send).

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

Quantity. May include up to four decimal places in core data.

revisionintegerminimum 0, maximum 9007199254740991

Latest observed return revision. Omit to use the current revision.

Ответы

200The updated return’s id.

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

Updated return id.

400Request validation failed or core rejected the update.

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обязательный

404No return with the given number was found in this team.

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обязательный

409The supplied revision is stale.

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/returns/by-number/{return_number}' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "memo": "Partial refund issued",
    "items": [
      {
        "order_item_id": 700201,
        "quantity": 5
      }
    ],
    "revision": 3
  }'

const response = await fetch("https://rest.boxhero-app.com/v1/returns/by-number/{return_number}", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "memo": "Partial refund issued",
    "items": [
      {
        "order_item_id": 700201,
        "quantity": 5
      }
    ],
    "revision": 3
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    "https://rest.boxhero-app.com/v1/returns/by-number/{return_number}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "memo": "Partial refund issued",
        "items": [
            {
                "order_item_id": 700201,
                "quantity": 5,
            },
        ],
        "revision": 3,
    },
)
data = response.json()

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

{
  "memo": "Partial refund issued",
  "items": [
    {
      "order_item_id": 700201,
      "quantity": 5
    }
  ],
  "revision": 3
}

Ответ

{
  "id": 90301
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-request",
  "title": "Request validation failed or core rejected the update.",
  "instance": "/returns/by-number/R-1001"
}

{
  "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/not-found",
  "title": "No return with the given number was found in this team.",
  "instance": "/returns/by-number/R-1001"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-request",
  "title": "The supplied revision is stale.",
  "instance": "/returns/by-number/R-1001"
}

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