> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to BoxHero

The BoxHero connector lets your AI agent act in each user's BoxHero account. Each user connects their own BoxHero access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

**Authentication:** Bearer Token
**Categories:** Productivity, Accounting & Finance
**Tools:** 60: 23 read, 28 write, 9 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BOXHERO)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the BoxHero connection

   In **AgentKit > Connections**, create a BoxHero connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'boxhero'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize BoxHero:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'boxhero_bundles_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "boxhero"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize BoxHero:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="boxhero_bundles_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their BoxHero credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'boxhero_bundle_get',
  toolInput: {
    bundle_id: 501,
  },
  connector: 'boxhero',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="boxhero_bundle_get",
    tool_input={
        "bundle_id": 501,
    },
    connection_name="boxhero",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `boxhero_bundle_get`

Get Bundle · Read-only

Get one bundle.
Returns its name, SKU, barcode, photo, cost, price and components.
Use bundles_list to find bundle IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bundle_id` (`integer`, required): Bundle ID. Maximum 2147483647. Example: 501.

Example input: `{"bundle_id":501}`

### `boxhero_bundles_list`

List Bundles · Read-only

List bundles (fixed groups of items sold or bought together), with cursor paging.
Returns each bundle's id, name, SKU, cost, price and components.
Use bundle_get for one bundle.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bundle_ids` (`array`, optional): Filter the list to specific bundle ids. Pass repeatedly (?bundle_ids=1&bundle_ids=2) or as a single value. Example: [501]
- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.

Example input: `{}`

### `boxhero_item_attr_get`

Get Item Attribute · Read-only

Get one custom item attribute spec.
Returns its id, name, type and rank.
Use item_attrs_list to find spec IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `attr_id` (`integer`, required): Attr ID. Maximum 2147483647. Example: 12.

Example input: `{"attr_id":12}`

### `boxhero_item_attrs_list`

List Item Attributes · Read-only

List the team's custom item attribute specs, ordered by rank.
Returns each spec's id, name, type (text, date, number or barcode) and rank.
Use spec IDs in an item's attrs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `boxhero_item_get`

Get Item · Read-only

Get one item by ID.
Returns its name, SKU, barcode, photo, cost, price, custom attributes and quantities per location.
Use item_get_by_sku when you only know the SKU.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): Item ID. Maximum 2147483647. Example: 1001.
- `location_ids` (`array`, optional): Scope the quantities breakdown (and the quantity total) to specific locations. Only requested locations with nonzero stock appear in quantities. When omitted, quantities covers every active location where the item has nonzero stock. Example: [3]

Example input: `{"item_id":1001}`

### `boxhero_item_get_by_sku`

Get Item by SKU · Read-only

Look up one item by SKU (case-insensitive).
Returns the same item details as item_get.
Use items_list to browse items.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sku` (`string`, required): Item SKU (case-insensitive). URL-encode special characters such as #, %, /, or spaces (e.g. SKU%2FABC for SKU/ABC). Example: TEA-GREEN-100G.
- `location_ids` (`array`, optional): Scope the quantities breakdown (and the quantity total) to specific locations. Only requested locations with nonzero stock appear in quantities. When omitted, quantities covers every active location where the item has nonzero stock. Example: [3]

Example input: `{"sku":"<sku>"}`

### `boxhero_items_list`

List Items · Read-only

List items with their stock, with cursor paging and optional item or location filters.
Returns each item's id, name, SKU, barcode, cost, price, custom attributes, total quantity and per-location quantities, plus cursor and has_more.
Use item_get_by_sku to look up one item by SKU.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `item_ids` (`array`, optional): Filter the list to specific item ids. Pass repeatedly (?item_ids=1&item_ids=2) or as a single value. Example: [1001, 1002]
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `location_ids` (`array`, optional): Scope the quantities breakdown (and the quantity total) to specific locations, and filter the list to items with nonzero stock at those locations. When omitted, all items are listed and quantities covers every active location where the item has nonzero stock. Example: [3]

Example input: `{}`

### `boxhero_location_get`

Get Location · Read-only

Get one location.
Returns its id, name, memo and total quantity.
Use locations_list to find location IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.

Example input: `{"location_id":3}`

### `boxhero_locations_list`

List Locations · Read-only

List the team's active locations with their total stock.
Returns each location's id, name, memo and quantity.
Only for teams in location mode.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `boxhero_members_list`

List Team Members · Read-only

List the members of the BoxHero team.
Returns each member's id, name, email and role.
Use member IDs as created_by_id filters on order lists.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `boxhero_partner_get`

Get Partner · Read-only

Get one supplier or customer.
Returns its type, name, phone, email, address and memo.
Use partners_list to find partner IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `partner_id` (`integer`, required): Partner ID. Maximum 2147483647. Example: 77.

Example input: `{"partner_id":77}`

### `boxhero_partners_list`

List Partners · Read-only

List suppliers and customers, optionally filtered by type, with cursor paging.
Returns each partner's id, type, name, phone, email, address and memo.
Use partner IDs on transactions and orders.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `type` (`integer`, optional): Filter by partner type. Pass 0 for suppliers only or 1 for customers only. Omit to list both. Maximum 1. Example: 0. One of: `0`, `1`.

Example input: `{}`

### `boxhero_price_list_get`

Get Price List · Read-only

Get one price list.
Returns its name, order type, currency and lines.
Use price_lists_list to find price list IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `price_list_id` (`integer`, required): Price list id. Maximum 2147483647. Example: 601.

Example input: `{"price_list_id":601}`

### `boxhero_price_lists_list`

List Price Lists · Read-only

List saved price lists for purchase or sales orders, with cursor paging.
Returns each list's id, name, order type, currency and lines.
Use price_list_get for one list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `order_type` (`string`, optional): "purchase" for purchase price lists; "sales" for sales price lists. A price list is tied to one order type. Example: purchase. One of: `purchase`, `sales`.

Example input: `{}`

### `boxhero_purchase_order_get`

Get Purchase Order · Read-only

Get one purchase order.
Returns its number, status, partner, dates, lines with fulfilled quantities, costs, tags, custom fields, totals and revision.
Use purchase_orders_list to find order IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order id. Use GET /orders/by-number/{order_number} to look up by order number. Maximum 2147483647. Example: 2201.

Example input: `{"order_id":2201}`

### `boxhero_purchase_orders_list`

List Purchase Orders · Read-only

List purchase orders, newest first, with filters by status, partner, number, tags, dates and creator, and cursor paging.
Returns each order's id, number, status, partner, order and estimated times, totals and revision.
Use purchase_order_get for its lines and fulfillment progress.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_by_id` (`integer`, optional): Filter by creator member id. Maximum 2147483647. Example: 42.
- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `estimated_after` (`string`, optional): Filter by estimated_time >= this timestamp. Example: 2026-01-01T00:00:00Z.
- `estimated_before` (`string`, optional): Filter by estimated_time < this timestamp. Example: 2026-02-01T00:00:00Z.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `order_number` (`string`, optional): Filter by exact order number. Whitespace is ignored and letters are uppercased. Example: PO-2026-0042.
- `ordered_after` (`string`, optional): Filter by order_time >= this timestamp. Example: 2026-01-01T00:00:00Z.
- `ordered_before` (`string`, optional): Filter by order_time < this timestamp. Example: 2026-02-01T00:00:00Z.
- `partner_id` (`integer`, optional): Filter by partner id. Maximum 2147483647. Example: 77.
- `statuses` (`array`, optional): Filter by one or more order statuses. Example: ["confirmed", "in-progress"]
- `tags` (`array`, optional): Filter by tags with all-match semantics. Example: ["urgent"]

Example input: `{}`

### `boxhero_return_get`

Get Sales Return · Read-only

Get one sales return.
Returns its number, status, source order, lines with received quantities, dates and revision.
Use returns_list to find return IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `return_id` (`integer`, required): Return id. Maximum 2147483647. Example: 3301.

Example input: `{"return_id":3301}`

### `boxhero_returns_list`

List Sales Returns · Read-only

List sales returns, newest first, with filters by status, partner, return or order number, tags, dates and creator, and cursor paging.
Returns each return's id, number, status, source order, dates and revision.
Use return_get for its lines.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_by_id` (`integer`, optional): Filter by creator member id. Maximum 2147483647. Example: 42.
- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `order_id` (`integer`, optional): Filter by source order id. Maximum 2147483647. Example: 2201.
- `order_number` (`string`, optional): Filter by exact source order number. Whitespace is ignored and letters are uppercased. Example: PO-2026-0042.
- `partner_id` (`integer`, optional): Filter by partner id. Maximum 2147483647. Example: 77.
- `return_number` (`string`, optional): Filter by exact return number. Whitespace is ignored and letters are uppercased. Example: RT-2026-0007.
- `returned_after` (`string`, optional): Filter by return_time >= this timestamp. Example: 2026-01-01T00:00:00Z.
- `returned_before` (`string`, optional): Filter by return_time < this timestamp. Example: 2026-02-01T00:00:00Z.
- `statuses` (`array`, optional): Filter by one or more return statuses. Example: ["confirmed", "in-progress"]
- `tags` (`array`, optional): Filter by tags with all-match semantics. Example: ["urgent"]

Example input: `{}`

### `boxhero_sales_order_get`

Get Sales Order · Read-only

Get one sales order.
Returns its number, status, partner, dates, lines with fulfilled quantities, costs, tags, custom fields, totals and revision.
Use sales_orders_list to find order IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order id. Use GET /orders/by-number/{order_number} to look up by order number. Maximum 2147483647. Example: 2201.

Example input: `{"order_id":2201}`

### `boxhero_sales_orders_list`

List Sales Orders · Read-only

List sales orders, newest first, with filters by status, partner, number, tags, dates and creator, and cursor paging.
Returns each order's id, number, status, partner, order and estimated times, totals and revision.
Use sales_order_get for its lines and fulfillment progress.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_by_id` (`integer`, optional): Filter by creator member id. Maximum 2147483647. Example: 42.
- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `estimated_after` (`string`, optional): Filter by estimated_time >= this timestamp. Example: 2026-01-01T00:00:00Z.
- `estimated_before` (`string`, optional): Filter by estimated_time < this timestamp. Example: 2026-02-01T00:00:00Z.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `order_number` (`string`, optional): Filter by exact order number. Whitespace is ignored and letters are uppercased. Example: PO-2026-0042.
- `ordered_after` (`string`, optional): Filter by order_time >= this timestamp. Example: 2026-01-01T00:00:00Z.
- `ordered_before` (`string`, optional): Filter by order_time < this timestamp. Example: 2026-02-01T00:00:00Z.
- `partner_id` (`integer`, optional): Filter by partner id. Maximum 2147483647. Example: 77.
- `statuses` (`array`, optional): Filter by one or more order statuses. Example: ["confirmed", "in-progress"]
- `tags` (`array`, optional): Filter by tags with all-match semantics. Example: ["urgent"]

Example input: `{}`

### `boxhero_team_get`

Get Linked Team · Read-only

Get the BoxHero team the API token belongs to.
Returns the team's id, name, inventory mode (basic or location) and currency.
Check the mode first: location tools and location_id only apply to teams in location mode.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `boxhero_transaction_get`

Get Transaction · Read-only

Get one inventory transaction, or an earlier revision of it.
Returns its type, time, locations, partner, memo, line items and revision.
Use transactions_list to find transaction IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tx_id` (`integer`, required): Tx ID. Maximum 2147483647. Example: 4401.
- `revision` (`integer`, optional): Fetch a specific historical revision of this transaction. Omit to fetch the latest revision. Maximum 9007199254740991. Example: 3.

Example input: `{"tx_id":4401}`

### `boxhero_transactions_list`

List Transactions · Read-only

List inventory transactions, newest first, optionally by type, with cursor paging.
Returns each transaction's id, type, time, locations, partner, memo and line items.
Use transaction_get for one transaction.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`integer`, optional): Page cursor. Pass the cursor field from the previous response to fetch the next page. Omit on the first call. Maximum 2147483647. Example: 0.
- `limit` (`integer`, optional): Page size. Accepts 1–100; defaults to 100. Maximum 100. Example: 50.
- `type` (`string`, optional): Filter by transaction type. Pass "in", "out", "move", or "adjust". Omit to list every type. Example: in. One of: `in`, `out`, `move`, `adjust`.

Example input: `{}`

### `boxhero_bundle_create`

Create Bundle · Write

Create a bundle from existing items and quantities.
Returns the bundle with its id.
Bundles hold no stock themselves; they can be used as order lines.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `components` (`array`, required): Items in the bundle, each by item_id or item_sku with the quantity per bundle. Bundles cannot contain other bundles. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 2}].
- `name` (`string`, required): Bundle display name. Example: Tea gift set.
- `sku` (`string`, required): Stock Keeping Unit. Must be unique across active bundles in the team. Example: GIFT-TEA-SET.
- `barcode` (`string`, optional): Primary bundle barcode. Example: 8801234567893.
- `cost` (`string`, optional): Cost per bundle, as a decimal string. Example: 2.75.
- `memo` (`string`, optional): Free-text memo. Example: Weekly restock.
- `photo_url` (`string`, optional): Public URL of the bundle photo. Example: https://cdn.example.com/photo.jpg.
- `price` (`string`, optional): Selling price per bundle, as a decimal string. Example: 4.50.

Example input: `{"components":[{"item_sku":"TEA-GREEN-100G","quantity":2}],"name":"<name>","sku":"<sku>"}`

### `boxhero_bundle_update`

Update Bundle · Write

Update a bundle's details or replace its component list.
Returns the updated bundle.
Passing components replaces the whole list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bundle_id` (`integer`, required): Bundle ID. Maximum 2147483647. Example: 501.
- `barcode` (`string`, optional): Primary bundle barcode. Example: 8801234567893.
- `components` (`array`, optional): Component list. When provided on update, this replaces the full component list. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 2}, {"item_sku": "MUG-WHITE", "quantity": 1}]
- `cost` (`string`, optional): Cost per bundle, as a decimal string. Example: 2.75.
- `memo` (`string`, optional): Free-text memo. Example: Weekly restock.
- `name` (`string`, optional): Bundle display name. Example: Tea gift set.
- `photo_url` (`string`, optional): Public URL of the bundle photo. Example: https://cdn.example.com/photo.jpg.
- `price` (`string`, optional): Selling price per bundle, as a decimal string. Example: 4.50.
- `sku` (`string`, optional): Stock Keeping Unit. Must be unique across active bundles in the team. Example: GIFT-TEA-SET.

Example input: `{"bundle_id":501}`

### `boxhero_item_attr_create`

Create Item Attribute · Write

Create a custom item attribute spec.
Returns the spec with its id.
Set values on items with item_update attrs.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Display name of the new attribute. 1+ characters. Example: Origin.
- `type` (`string`, required): Value type accepted by this attribute. text accepts any string; date accepts an ISO-8601 date (YYYY-MM-DD); number accepts a JSON number; barcode accepts a barcode string. File-type attributes exist in the BoxHero app but cannot be queried or set via the Open API. Example: text. One of: `text`, `date`, `number`, `barcode`.
- `rank` (`integer`, optional): Sort order. Lower values appear first; ties are broken by id. Ranks need not be contiguous. Optional on create — defaults to the next available rank (current MAX(rank) + 1). Example: 1.

Example input: `{"name":"<name>","type":"text"}`

### `boxhero_item_attr_rename`

Rename Item Attribute · Write

Rename a custom item attribute spec.
Returns the updated spec.
Its type cannot be changed.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `attr_id` (`integer`, required): Attr ID. Maximum 2147483647. Example: 12.
- `name` (`string`, required): New display name. 1+ characters. Example: Country of origin.

Example input: `{"attr_id":12,"name":"<name>"}`

### `boxhero_item_create`

Create Item · Write

Create an item, optionally seeding stock at one location with quantity and location_id.
Returns the created item with its id and SKU.
To add stock later, use transaction_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Item display name. 1–255 characters. Example: Green Tea 100g.
- `attrs` (`array`, optional): Custom attribute values. Official request format is [{ "id": , "value": }, ...]. The legacy object form { "": } is still accepted for compatibility. Example: [{"id": 12, "value": "Organic"}]
- `barcode` (`string`, optional): Primary barcode for the item. Optional. Example: 8801234567893.
- `cost` (`string`, optional): Cost per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: "12345.234". The team's currency is reported on GET /v1/teams/linked.
- `location_id` (`integer`, optional): Location at which to seed initial stock. Required together with the body's quantity when the team has more than one active location. Maximum 2147483647. Example: 3.
- `photo_url` (`string`, optional): Public URL of the item's photo. Optional. Example: https://cdn.example.com/photo.jpg.
- `price` (`string`, optional): Selling price per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: "12345.234". The team's currency is reported on GET /v1/teams/linked.
- `quantity` (`number`, optional): Initial on-hand quantity. Pass together with the location_id query to seed stock at a single location. Omit (or set null) to start with zero stock everywhere. Must be non-zero when provided. Example: 10.5.
- `sku` (`string`, optional): Stock Keeping Unit. Optional; a random SKU-XXXXXXXX is generated when omitted. Must be unique across the team. Example: TEA-GREEN-100G.

Example input: `{"name":"<name>"}`

### `boxhero_item_update`

Update Item · Write

Update an item's name, SKU, barcode, photo, cost, price or custom attributes. Only the fields you pass change.
Returns the updated item.
Stock quantities change through transaction_create, not here.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): Item ID. Maximum 2147483647. Example: 1001.
- `attrs` (`array`, optional): Patch attribute values. Official request format is [{ "id": , "value": }, ...]. Set value to null to remove that attribute. The legacy object form { "": } is still accepted for compatibility. Example: [{"id": 12, "value": "Organic"}]
- `barcode` (`string`, optional): New primary barcode. Example: 8801234567893.
- `cost` (`string`, optional): Cost per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: "12345.234". The team's currency is reported on GET /v1/teams/linked.
- `name` (`string`, optional): New display name. 1–255 characters. Example: Green Tea 100g.
- `photo_url` (`string`, optional): New photo URL. Pass an empty string to clear. Example: https://cdn.example.com/photo.jpg.
- `price` (`string`, optional): Selling price per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: "12345.234". The team's currency is reported on GET /v1/teams/linked.
- `sku` (`string`, optional): New SKU. An empty string is ignored (the SKU is left unchanged); an SKU cannot be cleared. Must remain unique within the team. Example: TEA-GREEN-100G.

Example input: `{"item_id":1001}`

### `boxhero_location_create`

Create Location · Write

Create a stock location, such as a warehouse or store.
Returns the location with its id.
Only for teams in location mode; your plan limits the number of locations.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Location display name. Must be unique within the team. Example: Austin warehouse.
- `memo` (`string`, optional): Free-text memo for the location. Example: Weekly restock.

Example input: `{"name":"<name>"}`

### `boxhero_location_update`

Update Location · Write

Update a location's name or memo.
Returns the updated location.
Use location_get to read the current values.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `memo` (`string`, optional): New memo. Pass an empty string to clear. Example: Weekly restock.
- `name` (`string`, optional): New display name. Must remain unique within the team. Example: Austin warehouse.

Example input: `{"location_id":3}`

### `boxhero_partner_create`

Create Partner · Write

Create a supplier or customer.
Returns the partner with its id.
Use it as partner_id on Stock In/Out transactions and orders.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Partner display name. 1–255 characters. Example: Leaf & Co.
- `type` (`integer`, required): Partner classification. 0 = supplier (used in Stock In transactions), 1 = customer (used in Stock Out transactions). Maximum 1. Example: 0. One of: `0`, `1`.
- `address` (`string`, optional): Postal address. Optional. Example: 500 Market St, San Francisco, CA.
- `email` (`string`, optional): Email address. Optional. Example: orders@leafco.example.com.
- `memo` (`string`, optional): Free-text memo. Optional. Example: Weekly restock.
- `phone` (`string`, optional): Phone number. Optional. Example: +1 415 555 0100.

Example input: `{"name":"<name>","type":0}`

### `boxhero_partner_update`

Update Partner · Write

Update a partner's name, phone, email, address or memo.
Returns the updated partner.
The partner type cannot be changed.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, required): Partner display name. 1–255 characters. Example: Leaf & Co.
- `partner_id` (`integer`, required): Partner ID. Maximum 2147483647. Example: 77.
- `address` (`string`, optional): Postal address. Optional. Example: 500 Market St, San Francisco, CA.
- `email` (`string`, optional): Email address. Optional. Example: orders@leafco.example.com.
- `memo` (`string`, optional): Free-text memo. Optional. Example: Weekly restock.
- `phone` (`string`, optional): Phone number. Optional. Example: +1 415 555 0100.

Example input: `{"name":"<name>","partner_id":77}`

### `boxhero_price_list_create`

Create Price List · Write

Create a price list of unit prices for items and bundles, tied to purchase or sales orders.
Returns the price list with its id.
Prices are decimal strings.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Price list lines, at least one. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a unit price as a decimal string. Example: [{"item_sku": "TEA-GREEN-100G", "price": "4.20"}].
- `name` (`string`, required): Price list display name. Example: Wholesale 2026.
- `order_type` (`string`, required): "purchase" for purchase price lists; "sales" for sales price lists. A price list is tied to one order type. Example: purchase. One of: `purchase`, `sales`.
- `currency_code` (`string`, optional): ISO 4217 currency code. Example: USD.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","price":"4.20"}],"name":"<name>","order_type":"purchase"}`

### `boxhero_price_list_update`

Update Price List · Write

Update a price list's name, order type, currency or lines.
Returns the updated price list.
Passing items replaces every line.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `price_list_id` (`integer`, required): Price list id. Maximum 2147483647. Example: 601.
- `currency_code` (`string`, optional): ISO 4217 currency code. Pass null to clear it. Example: USD.
- `items` (`array`, optional): Price list lines, at least one. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a unit price as a decimal string. Example: [{"item_sku": "TEA-GREEN-100G", "price": "4.20"}].
- `name` (`string`, optional): New price list name. Example: Wholesale 2026.
- `order_type` (`string`, optional): "purchase" for purchase price lists; "sales" for sales price lists. A price list is tied to one order type. Example: purchase. One of: `purchase`, `sales`.

Example input: `{"price_list_id":601}`

### `boxhero_purchase_order_create`

Create Purchase Order · Write

Create a purchase order with lines that each need a quantity and price. Set is_draft for a draft, or finalize_immediately with location_id to receive everything at once.
Returns the order with its id, number and revision.
Use purchase_order_fulfill to record partial receipts later.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Order lines. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a quantity and a unit price (decimal string); tax and discount objects are optional. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10, "price": "4.50"}].
- `costs` (`array`, optional): Additional costs to attach, in display order. Included in total_price but not in any items\[\] figure. Example: [{"name": "Shipping", "amount": "15.00"}]
- `currency_code` (`string`, optional): ISO 4217 currency code. On create, defaults to the team's currency when omitted. On update, omitting it keeps the stored value; it cannot be cleared. Example: USD.
- `custom_fields` (`array`, optional): Ordered custom field name-value pairs. Example: [{"name": "Project", "value": "Spring launch"}]
- `estimated_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `finalize_immediately` (`boolean`, optional): Fulfill all lines immediately and mark the order done. Example: true.
- `is_draft` (`boolean`, optional): Create the order in draft status. Example: true.
- `location_id` (`integer`, optional): Required when finalize_immediately is true. Maximum 2147483647. Example: 3.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_number` (`string`, optional): Order number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: PO-2026-0042.
- `order_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `partner_id` (`integer`, optional): Supplier for purchase orders or customer for sales orders. Pass null to clear. Maximum 2147483647. Example: 77.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":10,"price":"4.50"}]}`

### `boxhero_purchase_order_fulfill`

Receive Purchase Order Quantities · Write

Receive part of a purchase order: record a Stock In transaction for the given lines at a location.
Returns the created transaction and the order's new revision.
Use purchase_order_fulfill_all to receive everything that remains.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Lines to fulfill. Each names an item by item_id or item_sku with a positive quantity. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 5}].
- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":5}],"location_id":3,"order_id":2201}`

### `boxhero_purchase_order_fulfill_all`

Receive All Remaining Purchase Order Quantities · Write

Receive every remaining quantity of a purchase order at a location and mark it done.
Returns the created transaction and the updated order.
Use purchase_order_fulfill for a partial receipt.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"location_id":3,"order_id":2201}`

### `boxhero_purchase_order_status_update`

Update Purchase Order Status · Write

Set a purchase order's status (draft, confirmed, in-progress or done). Any status can move to any other.
Returns the updated order.
Recording stock with purchase_order_fulfill advances the status automatically.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `status` (`string`, required): Order status. Purchase and sales orders may also be draft. Recording stock through the order's transaction endpoints advances the status automatically: confirmed becomes in-progress once any quantity is recorded, and done once nothing remains. A done order is never reverted by such transaction changes; only an explicit status update can change it. Example: draft. One of: `draft`, `confirmed`, `in-progress`, `done`.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201,"status":"draft"}`

### `boxhero_purchase_order_update`

Update Purchase Order · Write

Update a purchase order's number, partner, dates, memo, custom fields, currency or lines. Passing items replaces every line.
Returns the updated order with its new revision.
Pass revision to avoid overwriting someone else's edit.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `costs` (`array`, optional): Replacement additional costs, in display order. Omit to preserve the current costs; pass an empty array to remove all of them. Example: [{"name": "Shipping", "amount": "15.00"}]
- `currency_code` (`string`, optional): ISO 4217 currency code. On create, defaults to the team's currency when omitted. On update, omitting it keeps the stored value; it cannot be cleared. Example: USD.
- `custom_fields` (`array`, optional): Ordered custom field name-value pairs. Example: [{"name": "Project", "value": "Spring launch"}]
- `estimated_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `items` (`array`, optional): Order lines. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a quantity and a unit price (decimal string); tax and discount objects are optional. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10, "price": "4.50"}].
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_number` (`string`, optional): Order number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: PO-2026-0042.
- `order_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `partner_id` (`integer`, optional): Supplier for purchase orders or customer for sales orders. Pass null to clear. Maximum 2147483647. Example: 77.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201}`

### `boxhero_return_create`

Create Sales Return · Write

Create a sales return against a sales order (by order_id or order_number), listing the order lines and quantities returned.
Returns the return with its id, number and revision.
Set finalize_immediately with location_id to put the stock back at once.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Return lines. Each gives the source sales order line ID (order_item_id, from sales_order_get) and the quantity returned. Example: [{"order_item_id": 9001, "quantity": 1}].
- `finalize_immediately` (`boolean`, optional): Receive all returned quantities immediately and mark the return done. Example: true.
- `location_id` (`integer`, optional): Required when finalize_immediately is true. Maximum 2147483647. Example: 3.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_id` (`integer`, optional): Source sales order id. Mutually exclusive with order_number. Maximum 2147483647. Example: 2201.
- `order_number` (`string`, optional): Source sales order number. Mutually exclusive with order_id. Example: SO-2026-0042.
- `order_revision` (`integer`, optional): Latest observed source order revision. Maximum 9007199254740991. Example: 3.
- `return_number` (`string`, optional): Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: RT-2026-0007.
- `return_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.

Example input: `{"items":[{"order_item_id":9001,"quantity":1}]}`

### `boxhero_return_receive`

Receive Returned Quantities · Write

Receive part of a sales return back into stock at a location.
Returns the created Stock In transaction and the return's new revision.
Use return_receive_all to receive everything that remains.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Lines to fulfill. Each names an item by item_id or item_sku with a positive quantity. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 5}].
- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `return_id` (`integer`, required): Return ID. Maximum 2147483647. Example: 3301.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":5}],"location_id":3,"return_id":3301}`

### `boxhero_return_receive_all`

Receive All Returned Quantities · Write

Receive every remaining quantity of a sales return at a location and mark it done.
Returns the created transaction and the updated return.
Use return_receive for a partial receipt.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `return_id` (`integer`, required): Return ID. Maximum 2147483647. Example: 3301.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"location_id":3,"return_id":3301}`

### `boxhero_return_update`

Update Sales Return · Write

Update a sales return's number, time, memo, status or lines. Passing items replaces every line.
Returns the updated return with its new revision.
Pass revision to avoid overwriting someone else's edit.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `return_id` (`integer`, required): Return ID. Maximum 2147483647. Example: 3301.
- `items` (`array`, optional): Return lines. Each gives the source sales order line ID (order_item_id, from sales_order_get) and the quantity returned. Example: [{"order_item_id": 9001, "quantity": 1}].
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_revision` (`integer`, optional): Latest observed source order revision when replacing items. Maximum 9007199254740991. Example: 3.
- `return_number` (`string`, optional): Return number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: RT-2026-0007.
- `return_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `revision` (`integer`, optional): Latest observed return revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.
- `status` (`string`, optional): Return status. Recording stock through the return's transaction endpoints advances the status automatically: confirmed becomes in-progress once any quantity is received, and done once nothing remains. A done return is never reverted by such transaction changes. Example: confirmed. One of: `confirmed`, `in-progress`, `done`.

Example input: `{"return_id":3301}`

### `boxhero_sales_order_create`

Create Sales Order · Write

Create a sales order with lines that each need a quantity and price. Set is_draft for a draft, or finalize_immediately with location_id to ship everything at once.
Returns the order with its id, number and revision.
Use sales_order_fulfill to record partial shipments later.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Order lines. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a quantity and a unit price (decimal string); tax and discount objects are optional. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10, "price": "4.50"}].
- `costs` (`array`, optional): Additional costs to attach, in display order. Included in total_price but not in any items\[\] figure. Example: [{"name": "Shipping", "amount": "15.00"}]
- `currency_code` (`string`, optional): ISO 4217 currency code. On create, defaults to the team's currency when omitted. On update, omitting it keeps the stored value; it cannot be cleared. Example: USD.
- `custom_fields` (`array`, optional): Ordered custom field name-value pairs. Example: [{"name": "Project", "value": "Spring launch"}]
- `estimated_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `finalize_immediately` (`boolean`, optional): Fulfill all lines immediately and mark the order done. Example: true.
- `is_draft` (`boolean`, optional): Create the order in draft status. Example: true.
- `location_id` (`integer`, optional): Required when finalize_immediately is true. Maximum 2147483647. Example: 3.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_number` (`string`, optional): Order number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: SO-2026-0042.
- `order_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `partner_id` (`integer`, optional): Supplier for purchase orders or customer for sales orders. Pass null to clear. Maximum 2147483647. Example: 77.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":10,"price":"4.50"}]}`

### `boxhero_sales_order_fulfill`

Ship Sales Order Quantities · Write

Ship part of a sales order: record a Stock Out transaction for the given lines at a location.
Returns the created transaction and the order's new revision.
Use sales_order_fulfill_all to ship everything that remains.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Lines to fulfill. Each names an item by item_id or item_sku with a positive quantity. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 5}].
- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":5}],"location_id":3,"order_id":2201}`

### `boxhero_sales_order_fulfill_all`

Ship All Remaining Sales Order Quantities · Write

Ship every remaining quantity of a sales order at a location and mark it done.
Returns the created transaction and the updated order.
Use sales_order_fulfill for a partial shipment.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.
- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Revision. Maximum 9007199254740991. Example: 3.
- `transaction_time` (`string`, optional): Transaction Time. Example: 2026-01-15T10:00:00Z.

Example input: `{"location_id":3,"order_id":2201}`

### `boxhero_sales_order_status_update`

Update Sales Order Status · Write

Set a sales order's status (draft, confirmed, in-progress or done). Any status can move to any other.
Returns the updated order.
Recording stock with sales_order_fulfill advances the status automatically.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `status` (`string`, required): Order status. Purchase and sales orders may also be draft. Recording stock through the order's transaction endpoints advances the status automatically: confirmed becomes in-progress once any quantity is recorded, and done once nothing remains. A done order is never reverted by such transaction changes; only an explicit status update can change it. Example: draft. One of: `draft`, `confirmed`, `in-progress`, `done`.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201,"status":"draft"}`

### `boxhero_sales_order_update`

Update Sales Order · Write

Update a sales order's number, partner, dates, memo, custom fields, currency or lines. Passing items replaces every line.
Returns the updated order with its new revision.
Pass revision to avoid overwriting someone else's edit.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `costs` (`array`, optional): Replacement additional costs, in display order. Omit to preserve the current costs; pass an empty array to remove all of them. Example: [{"name": "Shipping", "amount": "15.00"}]
- `currency_code` (`string`, optional): ISO 4217 currency code. On create, defaults to the team's currency when omitted. On update, omitting it keeps the stored value; it cannot be cleared. Example: USD.
- `custom_fields` (`array`, optional): Ordered custom field name-value pairs. Example: [{"name": "Project", "value": "Spring launch"}]
- `estimated_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `items` (`array`, optional): Order lines. Each names exactly one of item_id, item_sku, bundle_id or bundle_sku, with a quantity and a unit price (decimal string); tax and discount objects are optional. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10, "price": "4.50"}].
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `order_number` (`string`, optional): Order number. Whitespace is ignored and letters are uppercased. Use only letters, numbers, hyphens, and underscores. Auto-generated when omitted on create. Example: SO-2026-0042.
- `order_time` (`string`, optional): ISO 8601 timestamp or millisecond epoch. Example: 2026-01-15T10:00:00Z.
- `partner_id` (`integer`, optional): Supplier for purchase orders or customer for sales orders. Pass null to clear. Maximum 2147483647. Example: 77.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201}`

### `boxhero_transaction_create`

Create Transaction · Write

Record a Stock In, Stock Out, Move Stock or Adjust Stock transaction.
Returns the transaction with its id and revision.
In location mode, set to_location_id (and from_location_id for moves).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Line items, at least one. Each names an item by item_id or item_sku and gives a quantity: positive for Stock In and Move Stock, negative for Stock Out, and the new on-hand amount for Adjust Stock. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10}].
- `type` (`string`, required): 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). Example: in. One of: `in`, `out`, `move`, `adjust`.
- `from_location_id` (`integer`, optional): Source location. Required on Move Stock and rejected on every other transaction type. Maximum 2147483647. Example: 3.
- `memo` (`string`, optional): Free-text memo for the transaction. Example: Weekly restock.
- `partner_id` (`integer`, optional): Partner (supplier on Stock In, customer on Stock Out). Not allowed on Move Stock or Adjust Stock. Maximum 2147483647. Example: 77.
- `to_location_id` (`integer`, optional): 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. Maximum 2147483647. Example: 4.
- `tx_time` (`string`, optional): 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. Example: 2026-01-15T10:00:00Z.

Example input: `{"items":[{"item_sku":"TEA-GREEN-100G","quantity":10}],"type":"in"}`

### `boxhero_transaction_update`

Update Transaction · Write

Edit a transaction's time, locations, partner, memo or line items.
Returns the updated transaction with its new revision.
Pass revision to avoid overwriting someone else's edit.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tx_id` (`integer`, required): Tx ID. Maximum 2147483647. Example: 4401.
- `from_location_id` (`integer`, optional): New source location. Only allowed on Move Stock transactions; rejected with 400 on other types. Maximum 2147483647. Example: 3.
- `items` (`array`, optional): Line items, at least one. Each names an item by item_id or item_sku and gives a quantity: positive for Stock In and Move Stock, negative for Stock Out, and the new on-hand amount for Adjust Stock. Example: [{"item_sku": "TEA-GREEN-100G", "quantity": 10}].
- `memo` (`string`, optional): New memo. Pass an empty string to clear. Example: Weekly restock.
- `partner_id` (`integer`, optional): New counterparty. Pass null to clear an existing partner. Not allowed on Move Stock or Adjust Stock. Maximum 2147483647. Example: 77.
- `revision` (`integer`, optional): 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. Maximum 9007199254740991. Example: 3.
- `to_location_id` (`integer`, optional): New destination location. Maximum 2147483647. Example: 4.
- `tx_time` (`string`, optional): 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. Example: 2026-01-15T10:00:00Z.

Example input: `{"tx_id":4401}`

### `boxhero_bundle_delete`

Delete Bundle · Destructive

Delete a bundle.
Returns an empty response on success.
Its component items are not affected.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `bundle_id` (`integer`, required): Bundle ID. Maximum 2147483647. Example: 501.

Example input: `{"bundle_id":501}`

### `boxhero_item_attr_delete`

Delete Item Attribute · Destructive

Delete a custom item attribute spec and its values on every item.
Returns an empty response on success.
This cannot be undone.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `attr_id` (`integer`, required): Attr ID. Maximum 2147483647. Example: 12.

Example input: `{"attr_id":12}`

### `boxhero_item_delete`

Delete Item · Destructive

Delete an item.
Returns an empty response on success.
Its past transactions stay in the history.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): Item ID. Maximum 2147483647. Example: 1001.

Example input: `{"item_id":1001}`

### `boxhero_location_delete`

Delete Location · Destructive

Delete a location.
Returns an empty response on success.
Move its stock elsewhere first with a move transaction.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `location_id` (`integer`, required): Location ID. Maximum 2147483647. Example: 3.

Example input: `{"location_id":3}`

### `boxhero_partner_delete`

Delete Partner · Destructive

Delete a supplier or customer.
Returns an empty response on success.
Past transactions keep their partner reference.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `partner_id` (`integer`, required): Partner ID. Maximum 2147483647. Example: 77.

Example input: `{"partner_id":77}`

### `boxhero_purchase_order_delete`

Delete Purchase Order · Destructive

Delete a purchase order.
Returns an empty response on success.
Stock already recorded through it stays as transactions.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201}`

### `boxhero_return_delete`

Delete Sales Return · Destructive

Delete a sales return.
Returns an empty response on success.
Stock already received through it stays as transactions.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `return_id` (`integer`, required): Return ID. Maximum 2147483647. Example: 3301.
- `revision` (`integer`, optional): Latest observed return revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"return_id":3301}`

### `boxhero_sales_order_delete`

Delete Sales Order · Destructive

Delete a sales order.
Returns an empty response on success.
Stock already recorded through it stays as transactions.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`integer`, required): Order ID. Maximum 2147483647. Example: 2201.
- `memo` (`string`, optional): Memo. Example: Weekly restock.
- `revision` (`integer`, optional): Latest observed revision. Omit to use the current revision. Maximum 9007199254740991. Example: 3.

Example input: `{"order_id":2201}`

### `boxhero_transaction_delete`

Delete Transaction · Destructive

Delete a transaction and reverse its stock change.
Returns an empty response on success.
Pass revision to avoid deleting a transaction someone just edited.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `tx_id` (`integer`, required): Tx ID. Maximum 2147483647. Example: 4401.
- `memo` (`string`, optional): Optional memo recorded alongside the deletion (audit log). Example: Weekly restock.
- `revision` (`integer`, optional): Latest revision you have observed. Pass to enforce optimistic concurrency. Maximum 9007199254740991. Example: 3.

Example input: `{"tx_id":4401}`

## Related

Other Productivity connectors ([all 203](/agentkit/connectors/?category=productivity)):

- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Notion](/agentkit/connectors/notion/): Scalekit connector, OAuth, 51 tools
- [Google Workspace (DWD)](/agentkit/connectors/googledwd/): Scalekit connector, Service account, 100 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
