Add a line item to a purchase order

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders/{id}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quantity": 1.0001,
  "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "unit_cost": 123,
  "purchase_policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sort_order": 123,
  "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.arcuserp.com/v1/purchase-orders/{id}/items"

payload = {
    "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "quantity": 1.0001,
    "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "unit_cost": 123,
    "purchase_policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sort_order": 123,
    "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    product_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    quantity: 1.0001,
    variant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    unit_cost: 123,
    purchase_policy_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sort_order: 123,
    product_vendor_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.arcuserp.com/v1/purchase-orders/{id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/purchase-orders/{id}/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'product_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'quantity' => 1.0001,
    'variant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'unit_cost' => 123,
    'purchase_policy_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'sort_order' => 123,
    'product_vendor_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/purchase-orders/{id}/items"

	payload := strings.NewReader("{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/purchase-orders/{id}/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/purchase-orders/{id}/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sku": "<string>",
  "title": "<string>",
  "quantity": 123,
  "quantity_fulfilled": 123,
  "quantity_returned": 123,
  "received_floor": 123,
  "line_editability": {
    "qty": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked",
      "floor": 123
    },
    "unit_cost": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked",
      "warn_received_qty": 123
    },
    "delete": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked"
    },
    "notes": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked"
    }
  },
  "sell_rate": 123,
  "unit_price": 123,
  "list_price": 123,
  "pricing_rule_adjustment": 123,
  "coupon_adjustment": 123,
  "discount_amount": 123,
  "line_subtotal": 123,
  "tax_amount": 123,
  "line_total": 123,
  "adjustments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "source_type": "<string>",
      "source_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "source_label": "<string>",
      "per_unit_amount": 123,
      "quantity": 123,
      "line_amount": 123,
      "proration_ratio": 123,
      "applied_at": "2023-11-07T05:31:56Z"
    }
  ],
  "unit_cost": 123,
  "weight": 123,
  "is_tax_exempt": true,
  "product_tax_code": "<string>",
  "sort_order": 123,
  "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

"<unknown>"

Purchasing

Add a line item to a purchase order

Add a line item to an existing purchase order. The PO must be in draft or open status. If the PO is in draft and this is the first item, the PO auto-transitions to open and a purchase_order.sent event is emitted.

If a line for the same (product_id, variant_id) already exists on the PO, the incoming quantity is merged onto the existing line (de-dupe) rather than creating a duplicate row.

unit_cost is optional. When omitted, the canonical findBestPurchasePolicy resolver applies the best purchase pricing policy (effective-date filter + multiplier support). Kit products are rejected (create POs per component instead). Variant-parent products are rejected unless a specific variant_id is provided.

Rejected with 422 if the PO is pending_approval; withdraw and revise.

Required API key scope: purchasing:write

POST

purchase-orders

{id}

items

Add a line item to a purchase order

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders/{id}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quantity": 1.0001,
  "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "unit_cost": 123,
  "purchase_policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sort_order": 123,
  "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.arcuserp.com/v1/purchase-orders/{id}/items"

payload = {
    "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "quantity": 1.0001,
    "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "unit_cost": 123,
    "purchase_policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sort_order": 123,
    "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    product_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    quantity: 1.0001,
    variant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    unit_cost: 123,
    purchase_policy_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sort_order: 123,
    product_vendor_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.arcuserp.com/v1/purchase-orders/{id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/purchase-orders/{id}/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'product_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'quantity' => 1.0001,
    'variant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'unit_cost' => 123,
    'purchase_policy_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'sort_order' => 123,
    'product_vendor_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/purchase-orders/{id}/items"

	payload := strings.NewReader("{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/purchase-orders/{id}/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/purchase-orders/{id}/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"quantity\": 1.0001,\n  \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"unit_cost\": 123,\n  \"purchase_policy_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sort_order\": 123,\n  \"product_vendor_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sku": "<string>",
  "title": "<string>",
  "quantity": 123,
  "quantity_fulfilled": 123,
  "quantity_returned": 123,
  "received_floor": 123,
  "line_editability": {
    "qty": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked",
      "floor": 123
    },
    "unit_cost": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked",
      "warn_received_qty": 123
    },
    "delete": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked"
    },
    "notes": {
      "allowed": true,
      "reason": "po_pending_approval_edit_locked"
    }
  },
  "sell_rate": 123,
  "unit_price": 123,
  "list_price": 123,
  "pricing_rule_adjustment": 123,
  "coupon_adjustment": 123,
  "discount_amount": 123,
  "line_subtotal": 123,
  "tax_amount": 123,
  "line_total": 123,
  "adjustments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "source_type": "<string>",
      "source_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "source_label": "<string>",
      "per_unit_amount": 123,
      "quantity": 123,
      "line_amount": 123,
      "proration_ratio": 123,
      "applied_at": "2023-11-07T05:31:56Z"
    }
  ],
  "unit_cost": 123,
  "weight": 123,
  "is_tax_exempt": true,
  "product_tax_code": "<string>",
  "sort_order": 123,
  "product_vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

"<unknown>"

Authorizations

Authorization

string

header

required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Headers

Idempotency-Key

string

Optional idempotency key for safe retries (Stripe-style).

Maximum string length: 255

Path Parameters

string<uuid>

required

Body

application/json

product_id

string<uuid>

required

The product (SKU) to add. Cannot be a kit. If the product has variants, variant_id is also required.

quantity

number

required

Quantity ordered. Must be positive.

Required range: x >= 0.0001

variant_id

string<uuid> | null

Optional variant of product_id.

unit_cost

number | null

Optional unit cost override. Omit to auto-apply best purchase-pricing policy.

purchase_policy_id

string<uuid> | null

Optional pricing policy id to lock against (for audit trail).

sort_order

integer | null

Optional sort order on the PO; defaults to 0.

product_vendor_id

string<uuid> | null

Optional pointer at the exact product_vendors row this PO line is bound to. Persisted on order_items.product_vendor_id so the PO PDF / receiving / vendor email surface the operator-chosen vendor-part deterministically when a product has 2+ product_vendors rows for the same vendor. Validated against this entity (product_vendors -> products.entity_id) AND the line's (product_id, vendor_id); mismatched ids reject with 400 (invalid_product_vendor_id / product_vendor_product_mismatch / product_vendor_vendor_mismatch). Omit to let the PO PDF fall back to the deterministic LATERAL LIMIT 1 default-vendor-part pick.

Response

Line item added (or merged into existing line of same product+variant).

A line item on an order. Sub-resource of Order.

string<uuid>

entity_id

string<uuid>

read-only

Multi-tenant scoping column (Layer 1 isolation). Set automatically from the parent orders.entity_id and enforced by Postgres trigger trg_order_items_entity_parity (P0-ENTITY-ID-CHILD-TABLES, 2026-05-18). Cross-tenant writes are rejected at the database layer.

order_id

string<uuid>

product_id

string<uuid> | null

variant_id

string<uuid> | null

sku

string | null

title

string

quantity

integer

quantity_fulfilled

integer

read-only

quantity_returned

integer

read-only

received_floor

number

read-only

PURCHASE-ORDER lines only. The lowest quantity this line may be reduced to: the SAFEST of the line's quantity_fulfilled and its receipted-plus-damaged total, clamped at 0. The two sources disagree on migrated rows and on rows whose receipt was undone, so the maximum of both is used -- it can only ever refuse a reduction that either source forbids.

line_editability

object

PURCHASE-ORDER lines only. Per-field verdicts from the same predicate the write handlers enforce, so a client never has to restate the stage rules.

Show child attributes

sell_rate

number

Canonical Arcus per-unit price column (matches order_items.sell_rate).

unit_price

number

Public-API alias of sell_rate (Stripe/Shopify/QuickBooks convention). Always populated on read; equal to sell_rate. Set per NEW-GAP-API-V1-CALLER-UNIT-PRICE-SILENTLY-OVERRIDDEN 2026-05-17 closure.

list_price

number

pricing_rule_adjustment

number

read-only

Per-unit pricing-rule savings (list_price minus sell_rate, positive magnitude). Already baked into sell_rate (and therefore line_subtotal) per ASC 606 transaction-price pricing; surfaced for the gross-to-net bridge display, never re-subtracted.

coupon_adjustment

number

read-only

Per-line allocated coupon/order-level discount (signed; negative for a discount). Reflected in line_subtotal.

discount_amount

number

line_subtotal

number

read-only

tax_amount

number

read-only

line_total

number

read-only

adjustments

object[]

read-only

Per-line, per-source adjustment breakdown from order_item_adjustments (the canonical SSOT). Each entry attributes a signed line_amount to a source (pricing_rule | order_adjustment | coupon | manual_line_override | return_refund_adjust | restocking_fee). Empty array for lines with no allocations (and on legacy orders predating the writer). Industry parity: Shopify Admin GraphQL LineItem.discountAllocations[].

Show child attributes

unit_cost

number | null

weight

number | null

is_tax_exempt

boolean

product_tax_code

string | null

sort_order

integer

product_vendor_id

string<uuid> | null

For purchase_order document_type lines only: exact product_vendors row this line is bound to (NEW-GAP-ORDER-ITEMS-PRODUCT-VENDOR-ID-PROVENANCE, 2026-05-14). NULL for legacy PO lines and all non-PO doc types; PDF falls back to the deterministic default-vendor-part pick.

created_at

string<date-time>

read-only

updated_at

string<date-time>

read-only

Overview

All Endpoints

Add a line item to a purchase order

Authorizations

Headers

Path Parameters

Body

Response