> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Your Entity

> Set up locations, tax rates, currencies, payment terms, and other master data before going live with the Arcus ERP API.

# 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.

```bash theme={null}
# 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`.

<Warning>
  **`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.
</Warning>

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

```bash theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
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`).

```bash theme={null}
# 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%.

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

***

## 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.

```bash theme={null}
# 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):

```bash theme={null}
# 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.

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

***

## Step 5: Configure Product Categories

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

```bash theme={null}
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`.

```bash theme={null}
# 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.

```bash theme={null}
# 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.).

```bash theme={null}
# 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:**

1. Sign in to `https://app.arcuserp.com`.
2. Open **Admin**, then **Organization**.
3. Choose **Users**.
4. Select **Invite User**.
5. Enter the email, choose the starting role, select the target entities, and optionally
   restrict location access.
6. 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`.

<Note>
  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.
</Note>

***

## Recommended Setup Order

For a new entity, configure in this sequence:

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

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