Create an order (any document_type)

curl --request POST \
  --url https://api.arcuserp.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_type": "sales_order",
  "account_id": "c3f2a7b1-0e44-4f89-9d12-aabb0c123456",
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shipping_address_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "billing_address_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01",
  "shipping_method": "ups_ground",
  "line_items": [
    {
      "product_id": "11111111-2222-3333-4444-555555555555",
      "quantity": 5
    },
    {
      "product_id": "22222222-3333-4444-5555-666666666666",
      "quantity": 3
    },
    {
      "product_id": "33333333-4444-5555-6666-777777777777",
      "variant_id": "44444444-5555-6666-7777-888888888888",
      "quantity": 10
    }
  ],
  "discount": {
    "type": "percentage",
    "value": 5
  },
  "auto_compute_tax": true,
  "auto_allocate_inventory": true,
  "payments": [
    {
      "payment_method_id": "55555555-6666-7777-8888-999999999999",
      "amount": 750,
      "payment_type": "card",
      "auto_capture": true
    }
  ]
}
'

import requests

url = "https://api.arcuserp.com/v1/orders"

payload = {
    "document_type": "sales_order",
    "account_id": "c3f2a7b1-0e44-4f89-9d12-aabb0c123456",
    "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "shipping_address_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "billing_address_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01",
    "shipping_method": "ups_ground",
    "line_items": [
        {
            "product_id": "11111111-2222-3333-4444-555555555555",
            "quantity": 5
        },
        {
            "product_id": "22222222-3333-4444-5555-666666666666",
            "quantity": 3
        },
        {
            "product_id": "33333333-4444-5555-6666-777777777777",
            "variant_id": "44444444-5555-6666-7777-888888888888",
            "quantity": 10
        }
    ],
    "discount": {
        "type": "percentage",
        "value": 5
    },
    "auto_compute_tax": True,
    "auto_allocate_inventory": True,
    "payments": [
        {
            "payment_method_id": "55555555-6666-7777-8888-999999999999",
            "amount": 750,
            "payment_type": "card",
            "auto_capture": True
        }
    ]
}
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({
    document_type: 'sales_order',
    account_id: 'c3f2a7b1-0e44-4f89-9d12-aabb0c123456',
    location_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    shipping_address_id: 'd4e5f6a7-b8c9-0123-def4-567890abcdef',
    billing_address_id: 'e5f6a7b8-c9d0-1234-ef56-7890abcdef01',
    shipping_method: 'ups_ground',
    line_items: [
      {product_id: '11111111-2222-3333-4444-555555555555', quantity: 5},
      {product_id: '22222222-3333-4444-5555-666666666666', quantity: 3},
      {
        product_id: '33333333-4444-5555-6666-777777777777',
        variant_id: '44444444-5555-6666-7777-888888888888',
        quantity: 10
      }
    ],
    discount: {type: 'percentage', value: 5},
    auto_compute_tax: true,
    auto_allocate_inventory: true,
    payments: [
      {
        payment_method_id: '55555555-6666-7777-8888-999999999999',
        amount: 750,
        payment_type: 'card',
        auto_capture: true
      }
    ]
  })
};

fetch('https://api.arcuserp.com/v1/orders', 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/orders",
  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([
    'document_type' => 'sales_order',
    'account_id' => 'c3f2a7b1-0e44-4f89-9d12-aabb0c123456',
    'location_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'shipping_address_id' => 'd4e5f6a7-b8c9-0123-def4-567890abcdef',
    'billing_address_id' => 'e5f6a7b8-c9d0-1234-ef56-7890abcdef01',
    'shipping_method' => 'ups_ground',
    'line_items' => [
        [
                'product_id' => '11111111-2222-3333-4444-555555555555',
                'quantity' => 5
        ],
        [
                'product_id' => '22222222-3333-4444-5555-666666666666',
                'quantity' => 3
        ],
        [
                'product_id' => '33333333-4444-5555-6666-777777777777',
                'variant_id' => '44444444-5555-6666-7777-888888888888',
                'quantity' => 10
        ]
    ],
    'discount' => [
        'type' => 'percentage',
        'value' => 5
    ],
    'auto_compute_tax' => true,
    'auto_allocate_inventory' => true,
    'payments' => [
        [
                'payment_method_id' => '55555555-6666-7777-8888-999999999999',
                'amount' => 750,
                'payment_type' => 'card',
                'auto_capture' => true
        ]
    ]
  ]),
  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/orders"

	payload := strings.NewReader("{\n  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\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/orders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/orders")

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  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "order",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_number": "<string>",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "order_date": "2023-11-07T05:31:56Z",
  "due_date": "2023-11-07T05:31:56Z",
  "subtotal": 123,
  "discount_total": 123,
  "shipping_total": 123,
  "tax_total": 123,
  "fee_total": 123,
  "order_total": 123,
  "list_price_total": 123,
  "pricing_savings": 123,
  "amount_paid": 123,
  "balance_due": 123,
  "tax_exempt": true,
  "notes": "<string>",
  "internal_notes": "<string>",
  "invoice_number": "<string>",
  "is_on_hold": true,
  "hold_type": "<string>",
  "ship_complete": true,
  "source_platform": "<string>",
  "external_order_id": "<string>",
  "external_order_number": "<string>",
  "metadata": {},
  "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"
}

{
  "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"
}

Orders

Create an order (any document_type)

Atomic order create. A single POST creates the order header plus all inline children in one transactional write. Any child failure rolls back the entire graph — no half-baked orders.

Inline children accepted:

line_items[] — each entry specifies product_id, quantity, and optionally variant_id or sell_rate (override). Pricing engine runs per-item (qty-break pricing levels, account defaults). Variant guard: if the product has variants, variant_id is required.
discount — header-level discount applied as an order_adjustment row. {type: "percentage"|"flat", value: number}. Percentage is applied to the sum of line subtotals before tax.
auto_compute_tax: true — triggers AvaTax (or local rate) after all items are inserted. Requires a shipping_address_id (or inline shipping_address) that resolves to a US jurisdiction. Skips cleanly for tax-exempt accounts.
auto_allocate_inventory: true — reserves stock per line item at location_id (falls back to entity default location). Returns 422 insufficient_inventory with shortfall details if any line lacks available stock. The rollback is atomic: no line is reserved if any line fails.
payments[] — inline charge after the order and items are committed. Each entry: {payment_method_id, amount, payment_type?, auto_capture?}. payment_method_id is the Arcus internal UUID from account_payment_methods. Payment failure does NOT roll back the order (industry standard — order persists with payment_status: unpaid; retry via POST /v1/orders/{id}/payments). Results appear in _inline_payment_results[] in the response.

Response: fully hydrated order with line_items, payments, and tax_lines expanded. Developer never needs a follow-up GET.

Totals guarantee (NEW-GAP Wave A.5, 2026-05-15): the response order always lands with non-NULL subtotal, tax_total, shipping_total, and order_total — the canonical totals helper runs inside the same transaction as the order + line-item INSERTs, so a successful 201 implies the header has been recomputed against the just-inserted items. Tax + shipping totals are 0 when no AvaTax connector is active or the shipping address is incomplete (a warning is logged but never leaks into the response envelope).

Idempotency: supply Idempotency-Key header to safely retry without double-creating. The same key returns the same response.

See the Creating Orders guide for curl, TypeScript, and Python examples.

POST

orders

Create an order (any document_type)

curl --request POST \
  --url https://api.arcuserp.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_type": "sales_order",
  "account_id": "c3f2a7b1-0e44-4f89-9d12-aabb0c123456",
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shipping_address_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "billing_address_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01",
  "shipping_method": "ups_ground",
  "line_items": [
    {
      "product_id": "11111111-2222-3333-4444-555555555555",
      "quantity": 5
    },
    {
      "product_id": "22222222-3333-4444-5555-666666666666",
      "quantity": 3
    },
    {
      "product_id": "33333333-4444-5555-6666-777777777777",
      "variant_id": "44444444-5555-6666-7777-888888888888",
      "quantity": 10
    }
  ],
  "discount": {
    "type": "percentage",
    "value": 5
  },
  "auto_compute_tax": true,
  "auto_allocate_inventory": true,
  "payments": [
    {
      "payment_method_id": "55555555-6666-7777-8888-999999999999",
      "amount": 750,
      "payment_type": "card",
      "auto_capture": true
    }
  ]
}
'

import requests

url = "https://api.arcuserp.com/v1/orders"

payload = {
    "document_type": "sales_order",
    "account_id": "c3f2a7b1-0e44-4f89-9d12-aabb0c123456",
    "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "shipping_address_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "billing_address_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01",
    "shipping_method": "ups_ground",
    "line_items": [
        {
            "product_id": "11111111-2222-3333-4444-555555555555",
            "quantity": 5
        },
        {
            "product_id": "22222222-3333-4444-5555-666666666666",
            "quantity": 3
        },
        {
            "product_id": "33333333-4444-5555-6666-777777777777",
            "variant_id": "44444444-5555-6666-7777-888888888888",
            "quantity": 10
        }
    ],
    "discount": {
        "type": "percentage",
        "value": 5
    },
    "auto_compute_tax": True,
    "auto_allocate_inventory": True,
    "payments": [
        {
            "payment_method_id": "55555555-6666-7777-8888-999999999999",
            "amount": 750,
            "payment_type": "card",
            "auto_capture": True
        }
    ]
}
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({
    document_type: 'sales_order',
    account_id: 'c3f2a7b1-0e44-4f89-9d12-aabb0c123456',
    location_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    shipping_address_id: 'd4e5f6a7-b8c9-0123-def4-567890abcdef',
    billing_address_id: 'e5f6a7b8-c9d0-1234-ef56-7890abcdef01',
    shipping_method: 'ups_ground',
    line_items: [
      {product_id: '11111111-2222-3333-4444-555555555555', quantity: 5},
      {product_id: '22222222-3333-4444-5555-666666666666', quantity: 3},
      {
        product_id: '33333333-4444-5555-6666-777777777777',
        variant_id: '44444444-5555-6666-7777-888888888888',
        quantity: 10
      }
    ],
    discount: {type: 'percentage', value: 5},
    auto_compute_tax: true,
    auto_allocate_inventory: true,
    payments: [
      {
        payment_method_id: '55555555-6666-7777-8888-999999999999',
        amount: 750,
        payment_type: 'card',
        auto_capture: true
      }
    ]
  })
};

fetch('https://api.arcuserp.com/v1/orders', 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/orders",
  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([
    'document_type' => 'sales_order',
    'account_id' => 'c3f2a7b1-0e44-4f89-9d12-aabb0c123456',
    'location_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'shipping_address_id' => 'd4e5f6a7-b8c9-0123-def4-567890abcdef',
    'billing_address_id' => 'e5f6a7b8-c9d0-1234-ef56-7890abcdef01',
    'shipping_method' => 'ups_ground',
    'line_items' => [
        [
                'product_id' => '11111111-2222-3333-4444-555555555555',
                'quantity' => 5
        ],
        [
                'product_id' => '22222222-3333-4444-5555-666666666666',
                'quantity' => 3
        ],
        [
                'product_id' => '33333333-4444-5555-6666-777777777777',
                'variant_id' => '44444444-5555-6666-7777-888888888888',
                'quantity' => 10
        ]
    ],
    'discount' => [
        'type' => 'percentage',
        'value' => 5
    ],
    'auto_compute_tax' => true,
    'auto_allocate_inventory' => true,
    'payments' => [
        [
                'payment_method_id' => '55555555-6666-7777-8888-999999999999',
                'amount' => 750,
                'payment_type' => 'card',
                'auto_capture' => true
        ]
    ]
  ]),
  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/orders"

	payload := strings.NewReader("{\n  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\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/orders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/orders")

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  \"document_type\": \"sales_order\",\n  \"account_id\": \"c3f2a7b1-0e44-4f89-9d12-aabb0c123456\",\n  \"location_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"shipping_address_id\": \"d4e5f6a7-b8c9-0123-def4-567890abcdef\",\n  \"billing_address_id\": \"e5f6a7b8-c9d0-1234-ef56-7890abcdef01\",\n  \"shipping_method\": \"ups_ground\",\n  \"line_items\": [\n    {\n      \"product_id\": \"11111111-2222-3333-4444-555555555555\",\n      \"quantity\": 5\n    },\n    {\n      \"product_id\": \"22222222-3333-4444-5555-666666666666\",\n      \"quantity\": 3\n    },\n    {\n      \"product_id\": \"33333333-4444-5555-6666-777777777777\",\n      \"variant_id\": \"44444444-5555-6666-7777-888888888888\",\n      \"quantity\": 10\n    }\n  ],\n  \"discount\": {\n    \"type\": \"percentage\",\n    \"value\": 5\n  },\n  \"auto_compute_tax\": true,\n  \"auto_allocate_inventory\": true,\n  \"payments\": [\n    {\n      \"payment_method_id\": \"55555555-6666-7777-8888-999999999999\",\n      \"amount\": 750,\n      \"payment_type\": \"card\",\n      \"auto_capture\": true\n    }\n  ]\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "order",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_number": "<string>",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "order_date": "2023-11-07T05:31:56Z",
  "due_date": "2023-11-07T05:31:56Z",
  "subtotal": 123,
  "discount_total": 123,
  "shipping_total": 123,
  "tax_total": 123,
  "fee_total": 123,
  "order_total": 123,
  "list_price_total": 123,
  "pricing_savings": 123,
  "amount_paid": 123,
  "balance_due": 123,
  "tax_exempt": true,
  "notes": "<string>",
  "internal_notes": "<string>",
  "invoice_number": "<string>",
  "is_on_hold": true,
  "hold_type": "<string>",
  "ship_complete": true,
  "source_platform": "<string>",
  "external_order_id": "<string>",
  "external_order_number": "<string>",
  "metadata": {},
  "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"
}

{
  "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"
}

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

Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.

Maximum string length: 255

Body

application/json

document_type

enum<string>

required

Discriminator. sales_order and invoice are for customer accounts; purchase_order for vendors.

Available options:

quote,

sales_order,

invoice,

return,

purchase_order

account_id

string<uuid>

required

Customer or vendor account. Account defaults (pricing level, addresses, payment terms) are auto-inherited.

location_id

string<uuid>

Warehouse location for inventory allocation. Defaults to entity default location.

shipping_address_id

string<uuid>

Shipping address. Auto-resolved from account default when omitted.

billing_address_id

string<uuid>

Billing address. Auto-resolved from account default when omitted.

payment_term_id

string<uuid>

Payment terms (e.g. Net 30). Auto-resolved from account, channel, and entity default cascade.

sales_channel_id

string<uuid>

pricing_level_id

string<uuid>

Override pricing level. Auto-resolved from account default when omitted.

po_number

string

Customer purchase order number.

order_date

string<date-time>

Order date. Defaults to now.

notes

string

Customer-visible notes.

internal_notes

string

Internal-only notes.

customer_notes

string

requested_ship_date

string<date>

ship_complete

boolean

When true, do not ship partial. Inherited from account default.

ships_freight

boolean

tax_exempt

boolean

Mark order tax-exempt. Requires avatax_entity_code on the order or linked account.

avatax_entity_code

string

AvaTax exemption entity code (e.g. 'RESALE', 'EXEMPT').

sales_agent_id

string<uuid>

metadata

object

Arbitrary key-value metadata stored on the order.

line_items

object[]

Inline line items. Inserted atomically with the order. Any failure rolls back all items and the order header.

Show child attributes

discount

object

Header-level discount applied to the order subtotal.

Show child attributes

auto_compute_tax

boolean

Run AvaTax (or local rate) after all items are inserted. Requires shipping_address_id to resolve to a taxable jurisdiction.

auto_allocate_inventory

boolean

Reserve inventory per line item. Returns 422 with shortfall details if any line has insufficient stock. Rollback is atomic.

payments

object[]

Inline payment(s). Fired after the order is committed. Payment failure does NOT roll back the order.

Show child attributes

Response

Created order (hydrated with line_items, payments, tax_lines)

An Arcus ERP order document. One table holds quotes, sales_orders, invoices, returns, and purchase_orders -- always filter by document_type. entity_id is always from the API key (Layer 1 isolation).

string<uuid>

object

enum<string>

Available options:

order

entity_id

string<uuid>

read-only

order_number

string

read-only

document_type

enum<string>

Available options:

quote,

sales_order,

invoice,

return,

purchase_order

order_status

enum<string>

Available options:

draft,

confirmed,

partially_fulfilled,

fulfilled,

cancelled,

voided,

awaiting_ach_clearance,

on_hold

payment_status

enum<string>

Available options:

unpaid,

partially_paid,

paid,

overpaid,

refunded,

partially_refunded,

voided

fulfillment_status

enum<string>

Available options:

unfulfilled,

partially_fulfilled,

fulfilled

account_id

string<uuid> | null

location_id

string<uuid> | null

po_number

string | null

order_date

string<date-time> | null

due_date

string<date-time> | null

subtotal

number

discount_total

number

shipping_total

number

tax_total

number

fee_total

number

order_total

number

list_price_total

number

read-only

Derived (display-only): SUM(list_price * qty) over non-kit lines. The gross baseline of the gross-to-net bridge (List price minus pricing_savings equals subtotal). Never part of order_total.

pricing_savings

number

read-only

Derived (display-only): SUM(pricing_rule_adjustment * qty) over non-kit lines (positive magnitude). Per-unit pricing-rule savings already baked into subtotal via sell_rate (ASC 606 transaction price); shown as an informational List-to-Subtotal bridge, never subtracted from order_total.

amount_paid

number

read-only

SSOT: utils/ar-helpers.mjs::updateARBalance. Do not write directly.

balance_due

number

read-only

tax_exempt

boolean

delivery_option

enum<string>

Available options:

ship,

pick_up,

local_delivery

notes

string | null

internal_notes

string | null

invoice_number

string | null

read-only

invoice_type

enum<string> | null

Available options:

order,

manual,

proforma,

correction

is_on_hold

boolean

read-only

hold_type

string | null

read-only

ship_complete

boolean

source_platform

string | null

external_order_id

string | null

external_order_number

string | null

metadata

object | null

created_at

string<date-time>

read-only

updated_at

string<date-time>

read-only

List orders (all document_type values)Retrieve a single order by UUID or order_number