← All action domains

Inventory

20 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Confirm stock changes

inventory.apply_batchwriteconfirm

Atomically receive, remove, return, count or transfer stock for this account. Updates Commerce availability immediately and appends permanent movement history. Retry the same request UUID after a timeout. Counts reject changed stock; removals protect checkout holds; purchase-order receipts enforce remaining quantities. Returns restock only and never refund money.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
request_idstring (uuid)requiredUnique UUID per batch; reuse the same UUID and contents after a timeout to prevent duplicate stock changes.
kind"receive" | "remove" | "count" | "transfer" | "return"requiredReceive a delivery, remove stock, approve a physical count, transfer locations, or return units to stock. Returns do not refund payments.
location_idstring (uuid)requiredActive source location, or receiving/counting location.
destination_idstring (uuid)optionalDifferent active destination, required for transfers.
purchase_order_idstring (uuid)optionalOpen purchase order being received. Receipt cannot exceed outstanding quantities.
notestringrequiredPermanent reason or reference for this stock operation.
linesobject[]requiredDistinct items in the batch. All lines succeed together or none are changed.
lines[].item_idstring (uuid)requiredInventory item in the active account.
lines[].quantityintegerrequiredUnits moved; for counts this is the actual quantity on the shelf, including zero.
lines[].expected_versionintegeroptionalBalance version observed before counting. Required for counts; stale counts are rejected.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.apply_batch \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "kind": "receive",
    "location_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "note": "example",
    "lines": [
      {
        "item_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
        "quantity": 1
      }
    ]
  }'
Test with your API key

Over MCP the same operation is the tool inventory_apply_batch at https://app.chirply.io/api/mcp, same bearer token, same input.

Check stock batch

inventory.batch_statusread

Check whether an inventory request was committed, waiting for an in-flight database transaction with the same request UUID. Reads only; use this after a network error before editing a failed batch.

Parameters

FieldTypeRequiredDescription
request_idstring (uuid)requiredThe UUID used when confirming stock changes.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.batch_status \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_batch_status at https://app.chirply.io/api/mcp, same bearer token, same input.

Choose catalog product

inventory.catalog_productsread

Search physical Commerce products to link existing stock into Inventory without creating a second product. Reads only; choose an exact variant when has_variants is true.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
searchstringoptionalSearch existing product names or SKUs.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.catalog_products \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_catalog_products at https://app.chirply.io/api/mcp, same bearer token, same input.

Choose catalog variant

inventory.catalog_variantsread

List the sizes, colors or other variants of one account-owned Commerce product before linking its exact stock record to Inventory. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
product_idstring (uuid)requiredPhysical Commerce product ID in this account.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.catalog_variants \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_catalog_variants at https://app.chirply.io/api/mcp, same bearer token, same input.

Export inventory CSV

inventory.export_itemsreadadmin only

Export a page of inventory as formula-safe CSV, with a next offset for larger catalogs. Includes IDs, shared product fields, primary barcode and current quantities; quantities are read-only during import. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.export_items \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_export_items at https://app.chirply.io/api/mcp, same bearer token, same input.

View inventory item

inventory.get_itemread

Read one account-scoped inventory item with its shared Commerce product, barcodes, stock locations and checkout holds. Reads only.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredInventory item ID in this account.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.get_item \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_get_item at https://app.chirply.io/api/mcp, same bearer token, same input.

Import inventory items

inventory.import_itemswriteconfirmadmin only

Import up to 500 inventory metadata rows atomically. Explicit item IDs edit existing records; blank IDs create new draft Commerce products. Names, prices and stock tracking are shared with Commerce. Quantities are changed separately through receiving or counts. No messages or payments.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
rowsobject[]requiredValidated inventory item rows. Whole import succeeds or none of its changes persist.
rows[].idstring (uuid)optionalExisting inventory item ID to edit; omit to add an item.
rows[].product_idstring (uuid)optionalExisting physical Commerce product to track; omit to create a draft product.
rows[].variant_idstring (uuid)optionalExact variant of the selected product, required when the product has variants.
rows[].namestringrequiredProduct name, or variant name when editing a variant. Shared with Commerce.
rows[].skustringoptionalStock keeping code. Blank by default. Default: ""
rows[].currencystringoptionalLowercase ISO currency for a new product; existing product currency is preserved. Default: "usd"
rows[].price_amountintegerrequiredSelling price in minor currency units, e.g. 1299 for USD 12.99. Shared with Commerce.
rows[].cost_amountintegeroptionalReference unit cost in the product currency's minor units. Used for estimated stock value; not an accounting valuation. Default: 0
rows[].unitstringoptionalUnit label; quantities are whole units. Default each. Default: "each"
rows[].supplier_idstring (uuid) (or null)optionalPreferred supplier; omit to preserve an existing assignment.
rows[].reorder_pointintegeroptionalFlag low stock when available quantity reaches this level. Default 5. Default: 5
rows[].target_quantityintegeroptionalSuggested replenishment target. Default 20; open purchase order quantities are deducted from suggestions. Default: 20
rows[].is_activebooleanoptionalActive status; omit to preserve an existing item's status.
rows[].barcodesobject[]optionalBarcode aliases and pack quantities. Empty array clears all; omission preserves existing codes or imports an existing variant barcode.
rows[].barcodes[].codestringrequiredBarcode text, preserving leading zeros. Printable ASCII supported by Code 128 labels.
rows[].barcodes[].pack_quantityintegeroptionalUnits added per scan. A case barcode may represent 12 units; default 1. Default: 1

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.import_items \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "name": "Example",
        "price_amount": 1
      }
    ]
  }'
Test with your API key

Over MCP the same operation is the tool inventory_import_items at https://app.chirply.io/api/mcp, same bearer token, same input.

Prepare barcode labels

inventory.label_dataread

Return item names, prices and exact barcode values with pack quantities for printable labels. This prepares data only; it does not start a printer or change stock.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredInventory items whose barcode labels to prepare.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.label_data \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool inventory_label_data at https://app.chirply.io/api/mcp, same bearer token, same input.

Find stock

inventory.list_itemsread

Search and page the account's inventory with variant details, barcode aliases, location balances, checkout reservations and reference costs. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
searchstringoptionalSearch product/variant name or SKU.
activebooleanoptionalFilter active or archived inventory items; omit for both.
low_stockbooleanoptionalReturn items at or below the reorder point after checkout holds.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.list_items \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_list_items at https://app.chirply.io/api/mcp, same bearer token, same input.

View stock locations

inventory.list_locationsread

List stock locations in this account, including the default destination used for Commerce stock increases. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.list_locations \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_list_locations at https://app.chirply.io/api/mcp, same bearer token, same input.

View stock movements

inventory.list_movementsread

Page the account's permanent stock history, including opening quantities, barcode batches and changes from the shared Commerce catalog. Returns actor IDs, timestamps, locations, changes and resulting quantities. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
item_idstring (uuid)optionalInventory item ID in this account.
location_idstring (uuid)optionalLimit history to this location.
batch_idstring (uuid)optionalLimit history to this confirmed batch.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.list_movements \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_list_movements at https://app.chirply.io/api/mcp, same bearer token, same input.

View purchase orders

inventory.list_purchase_ordersread

List draft, ordered, partially received, received and cancelled purchase orders with their lines, quantities, delivery location and version. Reads only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.list_purchase_orders \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_list_purchase_orders at https://app.chirply.io/api/mcp, same bearer token, same input.

View inventory suppliers

inventory.list_suppliersread

List this account's supplier contact details and internal ordering notes. Reads only; no supplier is contacted.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.list_suppliers \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_list_suppliers at https://app.chirply.io/api/mcp, same bearer token, same input.

Scan barcode

inventory.lookup_barcoderead

Resolve a barcode exactly within this account, preserving leading zeros and returning its pack quantity. An unknown code returns item null and never creates or changes stock.

Parameters

FieldTypeRequiredDescription
codestringrequiredExact text emitted by a USB scanner, without its Enter/Tab terminator.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.lookup_barcode \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "example"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_lookup_barcode at https://app.chirply.io/api/mcp, same bearer token, same input.

View reorder list

inventory.reorderread

Find active items at or below their available-stock reorder point. Suggested quantities target the configured level after subtracting all outstanding ordered units. No orders are placed and no suppliers are contacted.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.reorder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool inventory_reorder at https://app.chirply.io/api/mcp, same bearer token, same input.

Save inventory item

inventory.save_itemwriteconfirmadmin only

Create or edit an inventory item linked to the shared Commerce catalog. New products start as drafts. Names, SKUs and selling prices also change in Commerce; stock tracking becomes enabled and sold-out policies apply immediately. Barcode aliases are unique within the account. No payments or messages.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalExisting inventory item ID to edit; omit to add an item.
product_idstring (uuid)optionalExisting physical Commerce product to track; omit to create a draft product.
variant_idstring (uuid)optionalExact variant of the selected product, required when the product has variants.
namestringrequiredProduct name, or variant name when editing a variant. Shared with Commerce.
skustringoptionalStock keeping code. Blank by default. Default: ""
currencystringoptionalLowercase ISO currency for a new product; existing product currency is preserved. Default: "usd"
price_amountintegerrequiredSelling price in minor currency units, e.g. 1299 for USD 12.99. Shared with Commerce.
cost_amountintegeroptionalReference unit cost in the product currency's minor units. Used for estimated stock value; not an accounting valuation. Default: 0
unitstringoptionalUnit label; quantities are whole units. Default each. Default: "each"
supplier_idstring (uuid) (or null)optionalPreferred supplier in this account; null clears it. Default: null
reorder_pointintegeroptionalFlag low stock when available quantity reaches this level. Default 5. Default: 5
target_quantityintegeroptionalSuggested replenishment target. Default 20; open purchase order quantities are deducted from suggestions. Default: 20
is_activebooleanoptionalWhether staff can select this inventory item for new operations. Archiving here preserves Commerce listing visibility. Default: true
barcodesobject[]optionalBarcode aliases and pack quantities. Empty array clears all; omission preserves existing codes or imports an existing variant barcode.
barcodes[].codestringrequiredBarcode text, preserving leading zeros. Printable ASCII supported by Code 128 labels.
barcodes[].pack_quantityintegeroptionalUnits added per scan. A case barcode may represent 12 units; default 1. Default: 1

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.save_item \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "price_amount": 1
  }'
Test with your API key

Over MCP the same operation is the tool inventory_save_item at https://app.chirply.io/api/mcp, same bearer token, same input.

Save stock location

inventory.save_locationwriteconfirmadmin only

Create or rename a stock location, or deactivate an empty location with no open purchase orders. The default Commerce location remains active. No messages or payments.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalExisting location ID; omit to create.
namestringrequiredLocation name, such as Main store or Stockroom.
is_activebooleanoptionalWhether staff can use this location. Locations holding stock or open purchase orders cannot be deactivated. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.save_location \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_save_location at https://app.chirply.io/api/mcp, same bearer token, same input.

Save purchase order

inventory.save_purchase_orderwriteconfirmadmin only

Save a draft purchase order, mark it ordered for later receiving, or cancel its unreceived remainder. Ordered lines cannot be edited; partial receipts remain in history. This records purchasing intent only: it does not contact the supplier, buy goods or move money.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalDraft purchase order to edit, or open order to cancel; omit to create.
versionintegeroptionalCurrent purchase order version, required when editing or cancelling.
supplier_idstring (uuid)requiredActive supplier in this account.
location_idstring (uuid)requiredActive delivery location.
currencystringoptionalOrder currency; must match all included items. Default: "usd"
expected_onstring (date) | ""optionalExpected delivery date YYYY-MM-DD, or blank. Default: ""
notesstringoptionalPurchase order notes. No messages are sent. Default: ""
status"draft" | "ordered" | "cancelled"optionalDraft can be edited; ordered freezes lines for receiving; cancelled closes remaining quantities. No purchase or payment is placed with the supplier. Default: "draft"
linesobject[]requiredDistinct purchase order lines.
lines[].item_idstring (uuid)requiredInventory item to order.
lines[].quantityintegerrequiredWhole units ordered.
lines[].cost_amountintegerrequiredAgreed unit cost in minor currency units.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.save_purchase_order \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "location_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "lines": [
      {
        "item_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
        "quantity": 1,
        "cost_amount": 1
      }
    ]
  }'
Test with your API key

Over MCP the same operation is the tool inventory_save_purchase_order at https://app.chirply.io/api/mcp, same bearer token, same input.

Save inventory supplier

inventory.save_supplierwriteconfirmadmin only

Create or update a supplier's name, contact information, address and internal notes in this account. No email, SMS, purchase or payment is sent.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalExisting supplier ID; omit to create.
namestringrequiredSupplier business name.
emailstring (email) | ""optionalSupplier email for your records. Saving never sends an email. Default: ""
phonestringoptionalSupplier phone for your records. Default: ""
addressstringoptionalSupplier postal address. Default: ""
notesstringoptionalOrdering instructions or internal notes. Default: ""
is_activebooleanoptionalActive suppliers can be chosen on new purchase orders. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.save_supplier \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool inventory_save_supplier at https://app.chirply.io/api/mcp, same bearer token, same input.

View inventory overview

inventory.summaryread

Read current item, unit, low-stock and open purchase-order totals for this account, with estimated stock value separated by currency. Reads only; no messages or charges.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/inventory.summary \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool inventory_summary at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=inventory — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.