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

name and code are required. The key needs the locations:write scope. Location types: warehouse, virtual, holding, writeoff, amazon, external, marketplace, dropship, overflow. Any other value is refused with a 400 that lists the valid ones. type defaults to warehouse. For warehouse and overflow locations, is_sellable and ships_from default to true; for every other type they default to false. is_receiving defaults to true. Warehouse, overflow and holding locations also get a quarantine bin created for them automatically. You can also add "is_default": true to the create call to make the new location the default in the same step. A location can be reviewed and edited in the app under Settings > Company > Locations.

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 ship-from location has no email, Arcus falls back to your entity’s support email and then to its accounting email. Set at least one of them, or an email on every ship-from location, 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"

Setting the default demotes the previous default location. When the location has a street address (address.line1), the same call also makes that address the entity’s ship-from origin for shipping rates and labels. 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
  }'

A term can also carry an early-payment discount. This one is 2/10 Net 30, a 2 percent discount if paid within 10 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-2-10-net-30" \
  -d '{
    "name": "2/10 Net 30",
    "days": 30,
    "discount_percent": 2,
    "discount_days": 10
  }'

Field	Type	Notes
`name`	string	Required.
`days`	integer	Days until the invoice is due. Defaults to 0.
`discount_percent`	number	Optional, from 0 to 100.
`discount_days`	integer	Optional, a whole number of days, 0 or more.
`is_default`, `is_active`	boolean	Optional. `is_active` defaults to `true`.

The key needs the payment_terms:write scope. 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"

The previous default is demoted, and a term you promote is made active if it was not. Delete 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. `name` is accepted as an alias; if you send both, `display_name` wins.
`rate`	decimal	Required. At least 0 and below 1 (e.g. 0.0825 = 8.25%). Anything else is refused with `rate_out_of_range`.
`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.
`jurisdiction_postal_code`	string	Optional postal code.
`tax_type`	enum	`sales` (the default), `use`, `vat`, `gst`, `hst`, `pst`, `excise`, `other`. Any other value is refused with `tax_type_invalid`.
`inclusive`	boolean	If true, tax is included in the price. Default: false.
`is_active`	boolean	Default: true.
`effective_from`, `effective_to`	date	Optional dates between which the rate applies.

Lookup precedence: AvaTax (if connected) > entity tax_rates > 0%. The call needs the tax_rates:write scope.

Step 4: Set Up Currencies and Exchange Rates (Optional)

USD is seeded for every entity at creation, and Arcus books every transaction in a single currency today. Because of that, the calls that create a currency or an exchange rate are switched off by default: until multi-currency is enabled for your entity, each of them returns 501 with the code feature_not_enabled, and nothing is written. Reading currencies and exchange rates is not affected. If you do not sell in more than one currency, skip this step. When multi-currency is enabled for your entity, add a currency like this:

# 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
  }'

code must be three uppercase letters (an ISO 4217 code), or the call is refused with code_not_iso_4217. The key needs the currencies:write scope. Then record an exchange rate for the day (append-only, one row per date). Currencies can be named by their code or by their id:

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": "USD",
    "to_currency": "EUR",
    "rate": 0.9234,
    "as_of_date": "2026-05-11",
    "source": "manual"
  }'

from_currency_id and to_currency_id are accepted in place of the codes and win if both are sent, and effective_date is an alias of as_of_date. The key needs the exchange_rates:write scope. An exchange rate is only a recorded snapshot. No order, payment or ledger entry reads it today, so it never changes an amount.

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
  }'

Only name is required, and the key needs the product_categories:write scope. The other fields you can set are default_length_uom, default_volume_uom, is_active (default true), is_final_sale (default false), and restocking_fee_pct and handling_fee_pct, each a number from 0 to 100.

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. A value outside this list is refused. Only name is required, and the key needs the pricing_levels:write scope. Per-product prices for a level are added separately through the product pricing call.

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"}'
# -> { "data": { "result": 0.75, "from_label": "Ounce", "to_label": "Pound", "from_uom": "OZ", "to_uom": "LB" } }

Convert takes unit codes, and both units must be of the same type; otherwise the call returns a 400 that says why. Add a custom unit with POST /v1/units-of-measure:

curl -X POST https://api.arcuserp.com/v1/units-of-measure \
  -H "Authorization: Bearer ark_live_ent_YOUR_ENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-uom-dz" \
  -d '{
    "uom_code": "DZ",
    "label": "Dozen",
    "uom_type": "quantity",
    "base_code": "EA",
    "to_base_factor": 12
  }'

uom_code, label, uom_type, base_code and to_base_factor are all required. uom_type is one of quantity, weight, length, volume or time. base_code must be an existing unit of that same type, and to_base_factor is how many of the base unit one of the new unit equals (a positive number). Codes are stored in uppercase. Creating needs the units_of_measure:write scope; listing and converting need units_of_measure:read. System UOMs (is_system: true) cannot be modified or deleted via the API; the call returns 403 system_row_locked. 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"]}'

name is required, and the tag’s slug is built from it (or from a slug you send); a slug that is already taken returns 409, and slugs that match a status word such as paid or draft are refused. applies_to must list at least one resource type from order, account, product, return and package. A tag with "is_actionable": true must also name an action_key that Arcus recognizes. The key needs the tags:write scope. The attach call returns the tags it applied in data.applied; a tag already on the resource is left alone. It is refused with 400 when a tag does not apply to that resource type or is not found in your entity, and with 403 when the resource is not in your entity. Attaching a tag to an order that came from a connected Shopify store also adds the tag to that store’s order. 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 Organization.
Choose Users (the page is Organization > 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 Settings > Team & Roles > 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 (optional; only once multi-currency is enabled for your entity)
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 in the app, then poll via API)
Invite team members (Organization > Users, in the app)

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

Get Started

Concepts

Guides

SDKs

Collections

Configuring Your Entity

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 (Optional)

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 (Optional)

​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 (Optional)

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