StockroomAPIOpen the app
Reference

Purchase orders

Drafts, lines, charges and the whole lifecycle: send, mark ordered, mark on the way, close, reopen, cancel what is left, archive, duplicate. Each move is its own call, and an illegal one is 422 invalid_transition rather than a silent write.

GETList purchase orders/purchase_ordersPOSTCreate a purchase order/purchase_ordersGETGet a purchase order/purchase_orders/{id}PATCHUpdate a purchase order/purchase_orders/{id}DELETEDelete a draft/purchase_orders/{id}GETAn order's history/purchase_orders/{id}/historyGETThe order as a PDF/purchase_orders/{id}/pdfPOSTAdd lines to an open order/purchase_orders/{id}/linesPOSTCancel what is still outstanding on a line/purchase_orders/{id}/lines/{line_id}/cancel_remainingPOSTEmail the order to the supplier/purchase_orders/{id}/sendPOSTMark a draft ordered/purchase_orders/{id}/mark_orderedPOSTRecord a shipment/purchase_orders/{id}/mark_in_transitPOSTClose an order/purchase_orders/{id}/closePOSTReopen a closed order/purchase_orders/{id}/reopenPOSTArchive an order/purchase_orders/{id}/archivePOSTUnarchive an order/purchase_orders/{id}/unarchivePOSTDuplicate an order as a new draft/purchase_orders/{id}/duplicate
#

List purchase orders

GETapi.stockroom.app/v2/purchase_orders
Scope: read · every key has itPaged

Summary rows - everything but receipts and payments (fetch the order for those). Filter by status (comma-separated), supplier_id, location_id (Shopify id), type, and archived (true for archived only, all for both; archived orders are left out by default).

Query
limitintegerquery
cursorstringquery
next_cursor from the previous page. A cursor that cannot be read is 400 invalid_cursor.
updated_at_minstring (date-time)query
updated_at_maxstring (date-time)query
created_at_minstring (date-time)query
created_at_maxstring (date-time)query
statusstringquery
Comma-separated. An unknown status is 400 invalid_filter.
supplier_idintegerquery
location_idintegerquery
typestringquery
purchasereturn
archivedstringquery
truefalseall
Responses
200
A page of purchase orders, oldest update first.
a page of PurchaseOrderSummary in data, with next_cursor and has_more
400 401 402 403 404 422 429
Request
curl "https://api.stockroom.app/v2/purchase_orders" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": [
    {
      "id": 1,
      "number": "PO-1042",
      "sequential_id": 1042,
      "status": "ordered",
      "type": "purchase",
      "archived": false,
      "archived_at": null,
      "source": "api",
      "supplier": {
        "id": 7,
        "name": "Acme Supply Co"
      },
      "supplier_id": 7,
      "currency": "USD",
      "exchange_rate": {
        "rate": 1.36,
        "base_currency": "USD",
        "date": "2026-09-02",
        "source": "api"
      },
      "reference": "INV-8812",
      "customer_order_number": null,
      "supplier_order_number": "SO-77120",
      "invoice_number": null,
      "account_number": "AC-2231",
      "notes": null,
      "expected_at": "2026-09-20",
      "payment_due_on": "2026-10-02",
      "payment_status": "unpaid",
      "paid_at": null,
      "location": {
        "id": 61234567890,
        "name": "Main warehouse"
      },
      "updates_stock": true,
      "ships_to_customer": false,
      "ship_to_address": null,
      "tax": {
        "rate_id": 1,
        "name": "Acme Supply Co",
        "rate_percent": 8.25,
        "taxes_included": false,
        "charges_taxable": true
      },
      "totals": {
        "currency": "USD",
        "subtotal": "300.00",
        "charges": "0.00",
        "tax": "24.75",
        "total": "324.75"
      },
      "lines": [
        {
          "id": 5001,
          "position": 1,
          "product_title": "Stoneware mug",
          "variant_title": "Blue",
          "sku": "MUG-BLU",
          "supplier_sku": "ACME-MUG-BLU",
          "barcode": "0123456789012",
          "pack_code": "CS12",
          "inventory_item_id": 44811223344,
          "variant_id": 40011223344,
          "product_id": 7011223344,
          "location_id": 61234567890,
          "quantity": 24,
          "cancelled_quantity": 0,
          "received_quantity": 12,
          "outstanding_quantity": 12,
          "unit_cost": "12.50",
          "discount_percent": null,
          "line_total": "300.00",
          "taxable": true,
          "tax_rate_percent": 8.25,
          "weight_grams": 250,
          "supplier_note": null,
          "internal_note": null
        }
      ],
      "charges": [],
      "shopify_sync": {
        "state": "synced",
        "attempted_at": "2026-09-11T08:12:46Z",
        "error": null
      },
      "sent_at": "2026-09-02T14:03:22Z",
      "ordered_at": "2026-09-02T14:05:10Z",
      "in_transit_at": null,
      "received_at": null,
      "closed_at": null,
      "created_at": "2026-09-01T10:00:00Z",
      "updated_at": "2026-09-11T08:12:44Z"
    }
  ],
  "next_cursor": "eyJpZCI6MTA0Mn0",
  "has_more": true
}
#

Create a purchase order

POSTapi.stockroom.app/v2/purchase_orders
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Creates a draft. Lines name a product by variant_id or inventory_item_id (Shopify ids) and Stockroom fills the SKU, barcode and titles from its catalog mirror; a line with neither is a custom line and needs a product_title. location_id is the Shopify location the order ships to. number is optional - the store's numbering assigns one.

BodyJSON
supplier_idinteger
numberstring or null
Leave out to let the store's numbering assign one.
currencystring or null
typestring
purchasereturn
return_reasonstring or null
return_source_po_idinteger or null
location_idinteger or null
Shopify location id the order ships to.
tax_rate_idinteger or null
taxes_includedboolean
charges_taxableboolean
referencestring or null
customer_order_numberstring or null
supplier_order_numberstring or null
invoice_numberstring or null
account_numberstring or null
notesstring or null
expected_atstring (date) or null
payment_due_onstring (date) or null
ship_to_overridestring or null
bill_to_overridestring or null
ships_to_customerboolean
updates_stockboolean
linesarray of PurchaseOrderLineInput
chargesarray of PurchaseOrderChargeInput
Responses
201
The new order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_id": 7,
  "number": "PO-1042",
  "currency": "USD",
  "type": "purchase",
  "return_reason": null,
  "return_source_po_id": null,
  "location_id": 61234567890,
  "tax_rate_id": null,
  "taxes_included": false,
  "charges_taxable": true,
  "reference": "INV-8812",
  "customer_order_number": null,
  "supplier_order_number": "SO-77120",
  "invoice_number": null,
  "account_number": "AC-2231",
  "notes": null,
  "expected_at": "2026-09-20",
  "payment_due_on": "2026-10-02",
  "ship_to_override": null,
  "bill_to_override": null,
  "ships_to_customer": false,
  "updates_stock": true,
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ],
  "charges": []
}'
Body
{
  "supplier_id": 7,
  "number": "PO-1042",
  "currency": "USD",
  "type": "purchase",
  "return_reason": null,
  "return_source_po_id": null,
  "location_id": 61234567890,
  "tax_rate_id": null,
  "taxes_included": false,
  "charges_taxable": true,
  "reference": "INV-8812",
  "customer_order_number": null,
  "supplier_order_number": "SO-77120",
  "invoice_number": null,
  "account_number": "AC-2231",
  "notes": null,
  "expected_at": "2026-09-20",
  "payment_due_on": "2026-10-02",
  "ship_to_override": null,
  "bill_to_override": null,
  "ships_to_customer": false,
  "updates_stock": true,
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ],
  "charges": []
}
Response 201
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Get a purchase order

GETapi.stockroom.app/v2/purchase_orders/{id}
Scope: read · every key has it

The full record with lines, charges, receipts and payments embedded.

Path
idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl "https://api.stockroom.app/v2/purchase_orders/1042" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Update a purchase order

PATCHapi.stockroom.app/v2/purchase_orders/{id}
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Partial. A draft accepts every field; an ordered or partially received order accepts what the Stockroom admin allows at that stage (notes, references, dates, charges, and lines that have not been received). Sending lines replaces the line set - include id on lines to keep.

Path
idintegerpathrequired
BodyJSON
supplier_idinteger
numberstring or null
Leave out to let the store's numbering assign one.
currencystring or null
typestring
purchasereturn
return_reasonstring or null
return_source_po_idinteger or null
location_idinteger or null
Shopify location id the order ships to.
tax_rate_idinteger or null
taxes_includedboolean
charges_taxableboolean
referencestring or null
customer_order_numberstring or null
supplier_order_numberstring or null
invoice_numberstring or null
account_numberstring or null
notesstring or null
expected_atstring (date) or null
payment_due_onstring (date) or null
ship_to_overridestring or null
bill_to_overridestring or null
ships_to_customerboolean
updates_stockboolean
linesarray of PurchaseOrderLineInput
chargesarray of PurchaseOrderChargeInput
Responses
200
The updated order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X PATCH "https://api.stockroom.app/v2/purchase_orders/1042" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_id": 7,
  "number": "PO-1042",
  "currency": "USD",
  "type": "purchase",
  "return_reason": null,
  "return_source_po_id": null,
  "location_id": 61234567890,
  "tax_rate_id": null,
  "taxes_included": false,
  "charges_taxable": true,
  "reference": "INV-8812",
  "customer_order_number": null,
  "supplier_order_number": "SO-77120",
  "invoice_number": null,
  "account_number": "AC-2231",
  "notes": null,
  "expected_at": "2026-09-20",
  "payment_due_on": "2026-10-02",
  "ship_to_override": null,
  "bill_to_override": null,
  "ships_to_customer": false,
  "updates_stock": true,
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ],
  "charges": []
}'
Body
{
  "supplier_id": 7,
  "number": "PO-1042",
  "currency": "USD",
  "type": "purchase",
  "return_reason": null,
  "return_source_po_id": null,
  "location_id": 61234567890,
  "tax_rate_id": null,
  "taxes_included": false,
  "charges_taxable": true,
  "reference": "INV-8812",
  "customer_order_number": null,
  "supplier_order_number": "SO-77120",
  "invoice_number": null,
  "account_number": "AC-2231",
  "notes": null,
  "expected_at": "2026-09-20",
  "payment_due_on": "2026-10-02",
  "ship_to_override": null,
  "bill_to_override": null,
  "ships_to_customer": false,
  "updates_stock": true,
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ],
  "charges": []
}
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Delete a draft

DELETEapi.stockroom.app/v2/purchase_orders/{id}
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Only a draft can be deleted. Anything that has been ordered is closed or archived instead, so its history survives.

Path
idintegerpathrequired
Responses
204
Deleted.
400 401 402 403 404 422 429
Request
curl -X DELETE "https://api.stockroom.app/v2/purchase_orders/1042" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 204
(no body)
#

An order's history

GETapi.stockroom.app/v2/purchase_orders/{id}/history
Scope: read · every key has it

The same log the Stockroom order page shows, newest first. by is the admin user; via names the API key when a key did it.

Path
idintegerpathrequired
Responses
200
History rows.
a page of HistoryRow in data, with next_cursor and has_more
400 401 402 403 404 422 429
Request
curl "https://api.stockroom.app/v2/purchase_orders/1042/history" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": [
    {
      "type": "purchase",
      "at": "2026-09-02T14:05:10Z",
      "by": "Dana Whitfield",
      "via": null,
      "data": {}
    }
  ]
}
#

The order as a PDF

GETapi.stockroom.app/v2/purchase_orders/{id}/pdf
Scope: read · every key has it

The document the store's PO template produces. ?received=true renders the receiving copy instead.

Path
idintegerpathrequired
Query
receivedbooleanquery
Responses
200
The PDF.
application/pdf
400 401 402 403 404 422 429
Request
curl "https://api.stockroom.app/v2/purchase_orders/1042/pdf" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
application/pdf
#

Add lines to an open order

POSTapi.stockroom.app/v2/purchase_orders/{id}/lines
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Appends lines to an ordered, in-transit or partially received order and pushes their incoming quantities to Shopify. A draft takes its lines through PATCH; a received or closed order refuses (invalid_transition).

Path
idintegerpathrequired
BodyJSON
linesarray of PurchaseOrderLineInputrequired
Responses
200
The order with the new lines.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/lines" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ]
}'
Body
{
  "lines": [
    {
      "id": 5001,
      "variant_id": 40011223344,
      "inventory_item_id": 44811223344,
      "product_title": "Stoneware mug",
      "variant_title": "Blue",
      "sku": "MUG-BLU",
      "supplier_sku": "ACME-MUG-BLU",
      "barcode": "0123456789012",
      "pack_code": "CS12",
      "location_id": 61234567890,
      "quantity": 24,
      "unit_cost": 12.5,
      "discount_percent": null,
      "weight_grams": 250,
      "taxable": true,
      "tax_rate_id": null,
      "supplier_note": null,
      "internal_note": null
    }
  ]
}
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Cancel what is still outstanding on a line

POSTapi.stockroom.app/v2/purchase_orders/{id}/lines/{line_id}/cancel_remaining
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Marks the unreceived quantity cancelled and retracts that much incoming stock from Shopify. The line and what was received stay.

Path
idintegerpathrequired
line_idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/lines/5001/cancel_remaining" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Email the order to the supplier

POSTapi.stockroom.app/v2/purchase_orders/{id}/send
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Queues the PO email with the PDF attached, exactly as Send does in Stockroom. to defaults to the supplier's email and cc to its saved CC list. A draft moves to ordered when the email is sent.

Path
idintegerpathrequired
BodyJSON
toarray of string (email)
ccarray of string (email)
subjectstring or null
messagestring or null
include_attachmentsboolean or null
Attach the order's own attachments.
include_csvboolean or null
Attach a CSV of the lines. Null follows the supplier's setting.
save_recipientsboolean or null
Remember to/cc on the supplier.
Responses
202
Queued.
400 401 402 403 404 422 429
202 answer, in data
queuedbooleanrequired
recipientsintegerrequired
Distinct addresses the email goes to.
toarray of stringrequired
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/send" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "orders@acme.example"
  ],
  "cc": [],
  "subject": "Purchase order PO-1042",
  "message": "The given data was invalid.",
  "include_attachments": false,
  "include_csv": false,
  "save_recipients": false
}'
Body
{
  "to": [
    "orders@acme.example"
  ],
  "cc": [],
  "subject": "Purchase order PO-1042",
  "message": "The given data was invalid.",
  "include_attachments": false,
  "include_csv": false,
  "save_recipients": false
}
Response 202
{
  "data": {
    "queued": true,
    "recipients": 2,
    "to": [
      "orders@acme.example"
    ]
  }
}
#

Mark a draft ordered

POSTapi.stockroom.app/v2/purchase_orders/{id}/mark_ordered
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Moves a draft to ordered without emailing and pushes the lines' quantities to Shopify as incoming stock (queued; see shopify_sync).

Path
idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/mark_ordered" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Record a shipment

POSTapi.stockroom.app/v2/purchase_orders/{id}/mark_in_transit
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Marks an ordered order in transit, with optional tracking. lines records a partial shipment.

Path
idintegerpathrequired
BodyJSON
tracking_numberstring or null
carrierstring or null
tracking_urlstring (uri) or null
expected_atstring (date) or null
shipped_atstring (date) or null
linesarray of object
line_idintegerrequired
quantitynumberrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/mark_in_transit" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "expected_at": "2026-09-20",
  "shipped_at": "2026-09-05",
  "lines": [
    {
      "line_id": 5001,
      "quantity": 24
    }
  ]
}'
Body
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "expected_at": "2026-09-20",
  "shipped_at": "2026-09-05",
  "lines": [
    {
      "line_id": 5001,
      "quantity": 24
    }
  ]
}
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Close an order

POSTapi.stockroom.app/v2/purchase_orders/{id}/close
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Ends an order that will not be received further and retracts its remaining incoming stock from Shopify. Closed is permanent apart from reopen.

Path
idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/close" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Reopen a closed order

POSTapi.stockroom.app/v2/purchase_orders/{id}/reopen
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key
Path
idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/reopen" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Archive an order

POSTapi.stockroom.app/v2/purchase_orders/{id}/archive
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key

Hides the order from the default list. close: true closes it first if it is still open.

Path
idintegerpathrequired
BodyJSON
closeboolean
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/archive" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "close": false
}'
Body
{
  "close": false
}
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Unarchive an order

POSTapi.stockroom.app/v2/purchase_orders/{id}/unarchive
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key
Path
idintegerpathrequired
Responses
200
The order.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/unarchive" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}
#

Duplicate an order as a new draft

POSTapi.stockroom.app/v2/purchase_orders/{id}/duplicate
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key
Path
idintegerpathrequired
Responses
201
The new draft.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/duplicate" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 201
{
  "data": {
    "receipts": [
      {
        "id": 311,
        "purchase_order_id": 1042,
        "received_at": null,
        "voided_at": null,
        "source": "api",
        "location": {
          "id": 61234567890,
          "name": "Main warehouse"
        },
        "invoice": {
          "reference": "INV-8812",
          "date": "2026-09-02",
          "total": "324.75"
        },
        "exchange_rate": 1.36,
        "rejected_disposition": "replace",
        "note": "Two cartons short; supplier notified.",
        "lines": [
          {
            "id": 5001,
            "line_id": 5001,
            "quantity": 24,
            "surplus_quantity": 0,
            "rejected_quantity": 0,
            "unit_cost": "12.50",
            "landed_unit_cost": "13.10",
            "allocated_charge_amount": "0.60"
          }
        ],
        "shopify_sync": {
          "state": "synced",
          "attempted_at": "2026-09-11T08:12:46Z",
          "error": null
        },
        "created_at": "2026-09-01T10:00:00Z",
        "updated_at": "2026-09-11T08:12:44Z"
      }
    ],
    "payments": [
      {
        "id": 52,
        "amount": "324.75",
        "currency": "USD",
        "paid_on": "2026-09-30",
        "method": "bank_transfer",
        "reference": "Wire 4471",
        "note": "Paid by wire.",
        "created_at": "2026-09-01T10:00:00Z"
      }
    ],
    "id": 1,
    "number": "PO-1042",
    "sequential_id": 1042,
    "status": "ordered",
    "type": "purchase",
    "archived": false,
    "archived_at": null,
    "source": "api",
    "supplier": {
      "id": 7,
      "name": "Acme Supply Co"
    },
    "supplier_id": 7,
    "currency": "USD",
    "exchange_rate": {
      "rate": 1.36,
      "base_currency": "USD",
      "date": "2026-09-02",
      "source": "api"
    },
    "reference": "INV-8812",
    "customer_order_number": null,
    "supplier_order_number": "SO-77120",
    "invoice_number": null,
    "account_number": "AC-2231",
    "notes": null,
    "expected_at": "2026-09-20",
    "payment_due_on": "2026-10-02",
    "payment_status": "unpaid",
    "paid_at": null,
    "location": {
      "id": 61234567890,
      "name": "Main warehouse"
    },
    "updates_stock": true,
    "ships_to_customer": false,
    "ship_to_address": null,
    "tax": {
      "rate_id": 1,
      "name": "Acme Supply Co",
      "rate_percent": 8.25,
      "taxes_included": false,
      "charges_taxable": true
    },
    "totals": {
      "currency": "USD",
      "subtotal": "300.00",
      "charges": "0.00",
      "tax": "24.75",
      "total": "324.75"
    },
    "lines": [
      {
        "id": 5001,
        "position": 1,
        "product_title": "Stoneware mug",
        "variant_title": "Blue",
        "sku": "MUG-BLU",
        "supplier_sku": "ACME-MUG-BLU",
        "barcode": "0123456789012",
        "pack_code": "CS12",
        "inventory_item_id": 44811223344,
        "variant_id": 40011223344,
        "product_id": 7011223344,
        "location_id": 61234567890,
        "quantity": 24,
        "cancelled_quantity": 0,
        "received_quantity": 12,
        "outstanding_quantity": 12,
        "unit_cost": "12.50",
        "discount_percent": null,
        "line_total": "300.00",
        "taxable": true,
        "tax_rate_percent": 8.25,
        "weight_grams": 250,
        "supplier_note": null,
        "internal_note": null
      }
    ],
    "charges": [],
    "shopify_sync": {
      "state": "synced",
      "attempted_at": "2026-09-11T08:12:46Z",
      "error": null
    },
    "sent_at": "2026-09-02T14:03:22Z",
    "ordered_at": "2026-09-02T14:05:10Z",
    "in_transit_at": null,
    "received_at": null,
    "closed_at": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T08:12:44Z"
  }
}