StockroomAPIOpen the app
Reference

Payments

Payments recorded against a purchase order, one row each, so a part payment is expressible. The order's payment_status and paid_at follow from the rows; mark paid and mark unpaid are the shortcuts.

GETList an order's payments/purchase_orders/{id}/paymentsPOSTRecord a payment/purchase_orders/{id}/paymentsDELETEDelete a payment/purchase_orders/{id}/payments/{payment_id}POSTMark an order paid/purchase_orders/{id}/mark_paidPOSTMark an order unpaid/purchase_orders/{id}/mark_unpaid
#

List an order's payments

GETapi.stockroom.app/v2/purchase_orders/{id}/payments
Scope: read · every key has it
Path
idintegerpathrequired
Responses
200
Payments, oldest first.
a page of Payment 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/payments" \
  -H "Authorization: Bearer $STOCKROOM_KEY"
Response 200
{
  "data": [
    {
      "id": 1,
      "amount": "324.75",
      "currency": "USD",
      "paid_on": "2026-09-30",
      "method": "bank_transfer",
      "reference": "INV-8812",
      "note": "Two cartons short; supplier notified.",
      "created_at": "2026-09-01T10:00:00Z"
    }
  ]
}
#

Record a payment

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

Payment status moves to partial or paid as the recorded total reaches the order total.

Path
idintegerpathrequired
BodyJSON
amountnumberrequired
In the order's currency.
paid_onstring (date)required
methodstring or null
cashcheckbank_transfercredit_cardother
referencestring or null
notestring or null
Responses
201
The order with the payment embedded.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X POST "https://api.stockroom.app/v2/purchase_orders/1042/payments" \
  -H "Authorization: Bearer $STOCKROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 324.75,
  "paid_on": "2026-09-30",
  "method": "bank_transfer",
  "reference": "INV-8812",
  "note": "Two cartons short; supplier notified."
}'
Body
{
  "amount": 324.75,
  "paid_on": "2026-09-30",
  "method": "bank_transfer",
  "reference": "INV-8812",
  "note": "Two cartons short; supplier notified."
}
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"
  }
}
#

Delete a payment

DELETEapi.stockroom.app/v2/purchase_orders/{id}/payments/{payment_id}
Scope: write:purchase_orders · orders, lines, receipts, paymentsTakes Idempotency-Key
Path
idintegerpathrequired
payment_idintegerpathrequired
Responses
200
The order without the payment.
PurchaseOrder in data
400 401 402 403 404 422 429
Request
curl -X DELETE "https://api.stockroom.app/v2/purchase_orders/1042/payments/52" \
  -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"
  }
}
#

Mark an order paid

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

Sets payment status to paid without recording an amount.

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_paid" \
  -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"
  }
}
#

Mark an order unpaid

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

Refused with payments_recorded while payments exist - delete them first.

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_unpaid" \
  -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"
  }
}