Create a price list

Creates a price list with at least one line item.

Each item provides exactly one of item_id, item_sku, bundle_id, or bundle_sku, plus a price.

POSThttps://rest.boxhero-app.com/v1/price-lists

Autorização

Authorizationstringobrigatório

Cabeçalho de autenticação Bearer no formato Bearer <token>, em que <token> é o seu token de API.

Corpo da requisição

order_typestringobrigatório

"purchase" for purchase price lists; "sales" for sales price lists. A price list is tied to one order type.

Valores possíveispurchasesales

namestringmin length 1, max length 255obrigatório

Price list display name.

currency_codestringmin length 3, max length 3

ISO 4217 currency code.

itemsarray of PriceListItemWriteobrigatório

Line items. At least one is required.

Mostrar propriedades

item_idintegerminimum 0, maximum 2147483647

Existing item id. Mutually exclusive with item_sku, bundle_id, bundle_sku.

item_skustringmin length 1, max length 255

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

bundle_idintegerminimum 0, maximum 2147483647

Existing bundle id. Mutually exclusive with item_id, item_sku, bundle_sku.

bundle_skustringmin length 1, max length 255

Bundle SKU (case-sensitive). Mutually exclusive with item_id, item_sku, bundle_id.

pricestringobrigatório

Unit price for this line.

Respostas

201The created price list’s id.

idintegerminimum 0, maximum 2147483647obrigatório

Id of the newly created price list.

400Request validation failed, an item/bundle reference was not found, or the same item/bundle appears more than once.

idstringobrigatório

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.

typestringobrigatório

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

Valores possíveis/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

titlestringobrigatório

Human-readable summary of the error, in English.

correlationIDstringobrigatório

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.

instancestringobrigatório

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.

Mostrar propriedades

patharray of string | numberobrigatório

messagestringobrigatório

401Missing or invalid API token.

idstringobrigatório

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.

typestringobrigatório

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

titlestringobrigatório

Human-readable summary of the error, in English.

correlationIDstringobrigatório

instancestringobrigatório

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.

Mostrar propriedades

patharray of string | numberobrigatório

messagestringobrigatório

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

idstringobrigatório

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.

typestringobrigatório

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

titlestringobrigatório

Human-readable summary of the error, in English.

correlationIDstringobrigatório

instancestringobrigatório

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.

Mostrar propriedades

patharray of string | numberobrigatório

messagestringobrigatório

Requisição

curl --request POST \
  --url 'https://rest.boxhero-app.com/v1/price-lists' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "order_type": "sales",
    "name": "Wholesale prices",
    "currency_code": "USD",
    "items": [
      {
        "item_sku": "SKU-12345678",
        "price": "12.50"
      },
      {
        "bundle_id": 4042,
        "price": "30"
      }
    ]
  }'

const response = await fetch("https://rest.boxhero-app.com/v1/price-lists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "order_type": "sales",
    "name": "Wholesale prices",
    "currency_code": "USD",
    "items": [
      {
        "item_sku": "SKU-12345678",
        "price": "12.50"
      },
      {
        "bundle_id": 4042,
        "price": "30"
      }
    ]
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    "https://rest.boxhero-app.com/v1/price-lists",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "order_type": "sales",
        "name": "Wholesale prices",
        "currency_code": "USD",
        "items": [
            {
                "item_sku": "SKU-12345678",
                "price": "12.50",
            },
            {
                "bundle_id": 4042,
                "price": "30",
            },
        ],
    },
)
data = response.json()

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

{
  "order_type": "sales",
  "name": "Wholesale prices",
  "currency_code": "USD",
  "items": [
    {
      "item_sku": "SKU-12345678",
      "price": "12.50"
    },
    {
      "bundle_id": 4042,
      "price": "30"
    }
  ]
}

Resposta

{
  "id": 81023
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-request",
  "title": "Request validation failed, an item/bundle reference was not found, or the same item/bundle appears more than once.",
  "instance": "/price-lists"
}

{
  "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/too-many-requests",
  "title": "Too many requests.",
  "instance": "/price-lists",
  "retryAfter": 60
}