Cancel a purchase order

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

import requests

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

payload = { "reason": "<string>" }
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({reason: '<string>'})
};

fetch('https://api.arcuserp.com/v1/purchase-orders/{id}/cancel', 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}/cancel",
  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([
    'reason' => '<string>'
  ]),
  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}/cancel"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\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}/cancel")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"reason\": \"<string>\"\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "purchase_order",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "draft",
  "po_date": "2023-11-07T05:31:56Z",
  "expected_date": "2023-11-07T05:31:56Z",
  "subtotal": 123,
  "tax_total": 123,
  "shipping_total": 123,
  "po_total": 123,
  "currency": "USD",
  "notes": "<string>",
  "internal_notes": "<string>",
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "approved_total": 123,
  "approval_stale": true,
  "header_editability": {},
  "billed_total": 123,
  "unbilled_balance": 123
}

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

Purchasing

Cancel a purchase order

Cancels a purchase order, transitioning it to status: cancelled. Only orders that have NOT yet been received can be cancelled; partially or fully received orders must be closed via the Close Short workflow on the staff app. Any inventory quantities on order are released back to ATP via the canonical handler.

Separation of Duties (SoD) gate (NEW-GAP-PURCHASING-CANCEL-PERMISSION-SOD-PHASE-2 2026-05-16): Beyond the purchasing:write API-key scope, the user who created the API key (the on_behalf_of_user_id recorded on the key) MUST hold the purchasing.cancel permission key (granted by default to owner / admin / manager / accountant; staff / warehouse / sales / auditor / viewer denied). This mirrors Stripe’s restricted-keys design (destructive ops require their own scope), NetSuite’s “Cancel Order” capability (the API caller’s role must carry it), Acumatica’s “Cancel Order” form access rights, and AICPA SOX SoD framework (destructive financial actions require separate authorization from creation). A 403 permission_denied response is returned when the key’s owning user lacks the RBAC; the denied attempt is recorded in the activity log (SoC2 CC6.1 + PCAOB AS 2201 §17).

Requires purchasing:write API-key scope AND the key-creator’s user role must carry purchasing.cancel.

POST

purchase-orders

{id}

cancel

Cancel a purchase order

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

import requests

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

payload = { "reason": "<string>" }
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({reason: '<string>'})
};

fetch('https://api.arcuserp.com/v1/purchase-orders/{id}/cancel', 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}/cancel",
  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([
    'reason' => '<string>'
  ]),
  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}/cancel"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\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}/cancel")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"reason\": \"<string>\"\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "purchase_order",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "draft",
  "po_date": "2023-11-07T05:31:56Z",
  "expected_date": "2023-11-07T05:31:56Z",
  "subtotal": 123,
  "tax_total": 123,
  "shipping_total": 123,
  "po_total": 123,
  "currency": "USD",
  "notes": "<string>",
  "internal_notes": "<string>",
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "approved_total": 123,
  "approval_stale": true,
  "header_editability": {},
  "billed_total": 123,
  "unbilled_balance": 123
}

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

Path Parameters

string<uuid>

required

Body

application/json

reason

string

Optional cancellation reason recorded on the activity log.

Response

Cancelled purchase order

A purchase order issued to a vendor.

string<uuid>

object

enum<string>

Available options:

purchase_order

entity_id

string<uuid>

read-only

po_number

string

read-only

vendor_id

string<uuid>

location_id

string<uuid> | null

status

enum<string>

read-only

Available options:

draft,

approved,

sent,

partially_received,

received,

closed,

cancelled

po_date

string<date-time>

expected_date

string<date-time> | null

subtotal

number

tax_total

number

shipping_total

number

po_total

number

currency

string

default:USD

notes

string | null

internal_notes

string | null

metadata

object | null

created_at

string<date-time>

read-only

updated_at

string<date-time>

read-only

approved_total

number | null

read-only

The order total as it stood when an approver approved this purchase order -- the basis they actually saw. NULL on every approval predating 2026-08-17 (no backfill) and NULL means "basis unknown", which is treated as fail-safe.

approval_stale

boolean

read-only

DERIVED, not stored. True when the order is approved AND its total has since risen above approved_total. The purchase order still receives normally; this is a non-blocking prompt to re-approve.

header_editability

object

read-only

Per-field verdicts for the header fields, from the same predicate the write handlers enforce. Keys: notes, internal_notes, due_date, expected_date, location_id, po_tracking_reference. Each is { allowed: boolean, reason: string|null } where reason is a token from the PoLineEditReason vocabulary.

Show child attributes

billed_total

number

read-only

How much of this purchase order's commitment a vendor bill has already taken over: the sum of total over every linked bill in open, partial, paid or written_off. 0 when no bill has been raised, never null.

unbilled_balance

number

read-only

What the purchase order STILL commits the buyer to: max(order_total - billed_total, 0), cents-quantized. Read this rather than balance_due, which on a purchase order is the ORIGINAL COMMITMENT the header was raised for and is never decremented when a bill is raised (the payable is the bill). Clamped at zero because a vendor may add freight on the bill and over-bill the order.

Overview

All Endpoints

Cancel a purchase order

Authorizations

Path Parameters

Body

Response