Update an account (PATCH allowlist)

Updates the specified fields of an account. Only explicitly allowlisted fields may be set via this endpoint (Rule 23 SSOT). The following fields are blocked and will return 422 forbidden_field if included: credit_balance, is_credit_hold (use POST /accounts//credit-hold to set/clear), merged_into_account_id, merged_at, and all 30+ analytics columns (total_orders, ttm_revenue, account_health_score, rfm_*, etc.).

Side effects:

• AvaTax recalc fires automatically on tax_exempt or avatax_entity_code change (AUDIT-037). Loader operators should disable AvaTax connector before bulk PATCH to avoid storms.
• Shopify customer sync fires post-commit if entity.settings.shopify_sync.customer_sync = true.

PATCH /accounts/{id}

Update an account (PATCH allowlist)

cURL

curl --request PATCH \
  --url https://api.arcuserp.com/v1/accounts/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "display_name": "<string>",
  "company_name": "<string>",
  "email": "<string>",
  "phone_main": "<string>",
  "phone_secondary": "<string>",
  "phone_mobile": "<string>",
  "website": "<string>",
  "payment_term_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "credit_limit": 123,
  "tax_exempt": true,
  "avatax_entity_code": "<string>",
  "tax_number": "<string>",
  "default_pricing_level_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "default_location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "default_shipping_method": "<string>",
  "enable_pro_portal": true,
  "is_active": true,
  "notes": "<string>",
  "metadata": {},
  "external_customer_id": "<string>"
}
'

200

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "account",
    "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "display_name": "<string>",
    "company_name": "<string>",
    "account_number": "<string>",
    "email": "<string>",
    "phone_main": "<string>",
    "phone_secondary": "<string>",
    "phone_mobile": "<string>",
    "website": "<string>",
    "payment_term_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "credit_limit": 123,
    "credit_balance": 123,
    "is_credit_hold": true,
    "tax_exempt": true,
    "avatax_entity_code": "<string>",
    "tax_number": "<string>",
    "default_pricing_level_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "default_location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "default_shipping_method": "<string>",
    "enable_pro_portal": true,
    "is_active": true,
    "notes": "<string>",
    "metadata": {},
    "stripe_customer_id": "<string>",
    "source_platform": "<string>",
    "external_customer_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

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

id · string · required

Account UUID or account_number (e.g. ACCT-001, CUST-00042). Polymorphic lookup: if the value is not a UUID it is resolved to a UUID via accounts.account_number within the entity scope before the record is fetched. (NEW-GAP-API-V1-POLYMORPHIC-LOOKUP-CROSS-RESOURCE 2026-05-20)

Body

application/json

Partial-update payload for an account. Only present fields are applied; omit a field to leave it unchanged. entity_id, id, account_number, credit_balance, is_credit_hold, and stripe_customer_id are read-only.

display_name · string

company_name · string | null

email · string | null

phone_main · string | null

phone_secondary · string | null

phone_mobile · string | null

website · string | null

payment_term_id · string<uuid> | null

credit_limit · number | null

tax_exempt · boolean

avatax_entity_code · string | null

tax_number · string | null

default_pricing_level_id · string<uuid> | null

default_location_id · string<uuid> | null

default_shipping_method · string | null

shipping_preference · enum<string> | null

Available options: always_freight, always_parcel, auto

enable_pro_portal · boolean

is_active · boolean

notes · string | null

metadata · object | null

external_customer_id · string | null

Response

200

application/json

Updated account object

data · object

An Arcus ERP account. Represents a customer, vendor, lead, or individual. account_type drives AR vs AP behavior: business/individual/lead = customer (AR); vendor = supplier (AP). entity_id is always from the API key (Layer 1 isolation).

Show child attributes