Configuring Your Entity

Before you start creating orders, recording payments, or managing inventory through the API, you need to configure your entity’s master data. This guide walks through the essential setup steps in the recommended order.

Step 1: Configure Locations

Every inventory movement, order, and fulfillment is tied to a location. At minimum you need one warehouse location.

# Create your primary warehouse
curl -X POST https://api.arcuserp.com/v1/locations \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-warehouse-001" \
  -d '{
    "name": "Main Warehouse",
    "code": "WH-MAIN",
    "type": "warehouse",
    "is_sellable": true,
    "ships_from": true,
    "is_receiving": true,
    "address": {
      "line1": "123 Commerce Drive",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US",
      "email": "shipping@yourcompany.com",
      "phone": "+1 555 555 5555"
    }
  }'

Location types: warehouse, virtual, holding, writeoff, storefront.

address.email is required for USPS label purchase. USPS rejects every label transaction when the ship-from address has no email ("Attribute address_from.email must not be empty"). The email is forwarded to the carrier for delivery-status notifications and is never printed on labels.address.phone is recommended. Required for freight LTL pickup scheduling and DHL Express international shipments.If a ships_from=true location is missing an email, Arcus falls back to entities.settings.email.support_email (Settings -> Communications) and then entities.settings.accounting_email (Settings -> Company). Set at least one to keep label purchase working entity-wide.

After creating your primary warehouse, designate it as the default:

curl -X POST https://api.arcuserp.com/v1/locations/LOCATION_ID/set-default \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN"

Layer 4 note: Orders, inventory balances, and fulfillment packages are scoped to location_id. Your API key’s entity owns all location rows.

Step 2: Set Up Payment Terms

Payment terms define when invoices are due. They appear on orders and can be assigned per account.

# Net 30 terms
curl -X POST https://api.arcuserp.com/v1/payment-terms \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-net30" \
  -d '{
    "name": "Net 30",
    "days": 30,
    "is_active": true
  }'

# COD terms (0 days)
curl -X POST https://api.arcuserp.com/v1/payment-terms \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-cod" \
  -d '{
    "name": "COD",
    "days": 0,
    "is_active": true
  }'

Set one term as the entity default:

curl -X POST https://api.arcuserp.com/v1/payment-terms/TERM_ID/set-default \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN"

RI guard: You cannot delete a payment term that is referenced by orders or accounts. Reassign references first.

Step 3: Configure Tax Rates

Tax rates are your entity’s fallback rates when AvaTax is not configured or unavailable. If AvaTax is active, these rates are bypassed automatically. Rates are stored as decimals (8.25% = 0.0825).

# Texas state sales tax
curl -X POST https://api.arcuserp.com/v1/tax_rates \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-tx-tax" \
  -d '{
    "display_name": "TX State Sales Tax",
    "rate": 0.0825,
    "jurisdiction_country": "US",
    "jurisdiction_state": "TX",
    "tax_type": "sales",
    "is_active": true
  }'

Field reference:

Field	Type	Notes
`display_name`	string	Required. Human label shown in the UI.
`rate`	decimal	Required. Value between 0 and 1 (e.g. 0.0825 = 8.25%).
`jurisdiction_country`	string	2-letter ISO code. Default: `US`.
`jurisdiction_state`	string	State abbreviation (TX, CA, NY).
`jurisdiction_county`	string	Optional county name.
`jurisdiction_city`	string	Optional city.
`tax_type`	enum	`sales`, `use`, `vat`, `gst`, `hst`, `pst`, `excise`, `other`.
`inclusive`	boolean	If true, tax is included in the price. Default: false.

Lookup precedence: AvaTax (if connected) > entity tax_rates > 0%.

The URL uses underscores (/v1/tax_rates). This will be standardized to hyphens in a future release.

Step 4: Set Up Currencies and Exchange Rates

USD is seeded for every entity at creation. If you sell in multiple currencies, add them here.

# Add Euro
curl -X POST https://api.arcuserp.com/v1/currencies \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-eur" \
  -d '{
    "code": "EUR",
    "name": "Euro",
    "symbol": "EUR",
    "decimals": 2
  }'

Then record an exchange rate for the day (append-only, one row per date):

# Get the currency IDs first
curl https://api.arcuserp.com/v1/currencies \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN"

# Post the exchange rate (requires UUIDs from the currencies response)
curl -X POST https://api.arcuserp.com/v1/exchange_rates \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fx-usd-eur-2026-05-11" \
  -d '{
    "from_currency_id": "USD_CURRENCY_UUID",
    "to_currency_id": "EUR_CURRENCY_UUID",
    "rate": 0.9234,
    "as_of_date": "2026-05-11",
    "source": "manual"
  }'

Lookup pattern: The system looks up the most-recent rate where as_of_date <= order_date for the (from, to) currency pair. Post a new row for each day you want to update.

Exchange rate fields use internal UUIDs today. A future release will accept currency codes directly (from_currency_code: "USD").

Step 5: Configure Product Categories

Categories organize your product catalog. They also carry default UOM settings.

curl -X POST https://api.arcuserp.com/v1/product-categories \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-cat-hardware" \
  -d '{
    "name": "Hardware",
    "default_quantity_uom": "EA",
    "default_weight_uom": "LB",
    "sort_order": 1
  }'

Step 6: Set Up Pricing Levels

Pricing levels (price books) let you assign different prices to different account types. The defaults_on and show_on fields accept account-type values: individual, lead, business, vendor.

# Wholesale level for business accounts
curl -X POST https://api.arcuserp.com/v1/pricing-levels \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-wholesale" \
  -d '{
    "name": "Wholesale",
    "description": "Wholesale pricing for established business accounts",
    "defaults_on": ["business"],
    "show_on": ["business", "lead"],
    "is_active": true
  }'

Vocab for defaults_on and show_on: individual, lead, business, vendor.

Step 7: Configure Units of Measure

System UOMs (EA, LB, OZ, IN, CS, etc.) are pre-seeded and cannot be modified. You can add custom UOMs for your industry.

# List available UOMs grouped by type
curl https://api.arcuserp.com/v1/units-of-measure \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN"

# Convert between UOMs
curl -X POST https://api.arcuserp.com/v1/units-of-measure/convert \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 12, "from_uom": "OZ", "to_uom": "LB"}'
# -> { "result": 0.75, "from_label": "Ounce", "to_label": "Pound" }

System UOMs (is_system: true) cannot be modified or deleted via the API. They are shared across all entities.

Step 8: Tags (Optional)

Tags let you label orders, accounts, and products for operational workflows. System tags (is_system: true) are pre-seeded and control fulfillment behavior (Hold Shipment, Block New Orders, etc.).

# Create a custom tag
curl -X POST https://api.arcuserp.com/v1/tags \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-tag-vip" \
  -d '{
    "name": "Priority",
    "color": "#F59E0B",
    "applies_to": ["order", "account"],
    "is_actionable": false
  }'

# Attach to an order
curl -X POST https://api.arcuserp.com/v1/tags/order/ORDER_ID \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["TAG_ID"]}'

Dual-scope requirement: Attaching a tag to a resource requires BOTH tags:write AND the resource’s write scope (e.g. orders:write for orders, accounts:write for accounts).

Step 9: Invite Your Team

Master data without people to act on it does not run an entity. Before going live, invite the operations, accounting, fulfillment, and support team members who will use Arcus. User management is currently a UI workflow. It is intentionally not exposed in the public v1 API surface because invitations, role assignment, MFA enrollment, and entity membership are organization-level concerns that span beyond a single entity’s API key scope. Send your ops admin to the in-app Organization Users page to send invitations. Where to invite users:

Sign in to https://app.arcuserp.com.
Open Admin, then Organization.
Choose Users.
Select Invite User.
Enter the email, choose the starting role, select the target entities, and optionally restrict location access.
Send the invitation. The invited user receives an email, sets a password, completes MFA, and lands in the entity you assigned.

What to verify after inviting your first admin:

The user appears in Organization Users with a Pending status until the invitation is accepted.
After acceptance, the user appears in Entity Team for the entity you chose.
The user can sign in and see the modules their role allows.

For the full UI walkthrough including roles, custom permissions, location restriction (Layer 4 isolation), MFA enrollment, and offboarding, read the support article: https://arcuserp.mintlify.app/support/settings/users. For role design, custom roles, and the Role Coverage Report, read: https://arcuserp.mintlify.app/support/settings/roles-permissions.

When user management is exposed in a future API release, this guide will gain curl examples for invite, role assignment, location restriction, and deactivation. Until then, treat user invite as a one-time bootstrap step done in the UI before your API integration starts shipping real orders.

Recommended Setup Order

For a new entity, configure in this sequence:

Locations (warehouse + receiving dock)
Payment Terms (Net 30, COD, CIA)
Tax Rates (if not using AvaTax)
Currencies + Exchange Rates (if multi-currency)
Product Categories
Pricing Levels
Units of Measure (custom only; system UOMs already exist)
Tags (optional, system tags pre-seeded)
Integrations (Stripe, Shippo, AvaTax via Settings > Integrations UI, then poll via API)
Invite team members (Admin > Organization > Users, in the app)

After this setup, you are ready to create accounts, products, and orders.

​Configuring Your Entity

​Step 1: Configure Locations

​Step 2: Set Up Payment Terms

​Step 3: Configure Tax Rates

​Step 4: Set Up Currencies and Exchange Rates

​Step 5: Configure Product Categories

​Step 6: Set Up Pricing Levels

​Step 7: Configure Units of Measure

​Step 8: Tags (Optional)

​Step 9: Invite Your Team

​Recommended Setup Order

Configuring Your Entity

Step 1: Configure Locations

Step 2: Set Up Payment Terms

Step 3: Configure Tax Rates

Step 4: Set Up Currencies and Exchange Rates

Step 5: Configure Product Categories

Step 6: Set Up Pricing Levels

Step 7: Configure Units of Measure

Step 8: Tags (Optional)

Step 9: Invite Your Team

Recommended Setup Order