Companies: customer organizations

A company is the core entity that represents one of your customers in ArcenPay. Every billing operation, entitlement check, and subscription activation resolves against a company record. Companies hold identity fields (name, wallet, email), an optional external ID from your own system, and the resolved state of their active plan, add-on grants, feature overrides, and users.

What a company contains

Field	Description
`name`	Display name for the company.
`walletAddress`	Wallet address (EVM, Stellar, or Solana) used for on-chain subscription payments.
`email`	Billing or contact email.
`externalId`	Your system’s ID for this company (optional, for cross-system mapping).
`traits`	Arbitrary key-value metadata for feature flag targeting.
`activePlan`	The currently assigned subscription plan with tier, price, and interval.
`entitlements`	Resolved feature access state across plan, add-ons, and overrides.
`users`	Associated user accounts for this company.

Company ID vs. external ID

ArcenPay assigns every company an internal ID with the cm_... prefix. When you create a company, you can also pass your own id field — this is stored as the externalId and lets you resolve companies using your own identifiers. Most API operations accept either the ArcenPay internal ID or the external ID for resolution. Entitlement checks can also resolve by wallet or email.

Creating companies

Companies can be created in three ways:

Via the dashboard — under Companies, click New Company.
Via the API — POST /api/v1/companies with name, wallet, email, and optional traits.
Via ArcenClient.identify() — the Node SDK’s identify() call upserts company and user records atomically.

import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY! });

// Explicit creation
await client.createCompany({
  id: "company_123",
  name: "Acme Corp",
  wallet: "0xabc...",
  email: "[email protected]",
});

// Implicit upsert via identify
const session = await client.identify({
  company: { id: "company_123", wallet: "0xabc...", name: "Acme Corp" },
  user: { id: "user_123", wallet: "0xabc..." },
});

Wallet uniqueness

Each wallet address can only belong to one company in a team. If you try to create a company with a wallet that already exists, the API returns 409 with the conflicting companyId.

Plan assignment

A company’s activePlan determines its subscription. You can assign or change plans via:

PATCH /api/v1/companies/:id with activePlanId for manual assignment
POST /api/v1/companies/plan for subscription plan changes (upgrade/downgrade)
POST /api/v1/subscriptions/activate for first-time on-chain activation

Traits and targeting

Traits are arbitrary key-value pairs stored on the company record. They’re used by feature flag rules for conditional targeting — for example, enabling a feature only for companies where traits.plan === "enterprise".

await client.updateCompany("cm_abc123", {
  traits: { industry: "fintech", region: "eu" },
});

SDK methods

Method	Description
`client.createCompany(params)`	Create a new company
`client.getCompany(id)`	Get full company detail including entitlements
`client.updateCompany(id, params)`	Update name, traits, plan, or add-on IDs
`client.listCompanies(opts)`	Paginated list with search

Company deletion is dashboard-managed; ArcenClient does not expose a delete method. See the Companies API reference for full endpoint details.

Next steps

Subscriptions — understand how subscriptions activate against a company
Entitlements — how a company’s access is resolved at runtime
Feature flags — target companies with flag rules and overrides

Get started

Core concepts

Guides

Integrations

Companies: customer organizations

What a company contains

Company ID vs. external ID

Creating companies

Wallet uniqueness

Plan assignment

Traits and targeting

SDK methods

Next steps

​What a company contains

​Company ID vs. external ID

​Creating companies

​Wallet uniqueness

​Plan assignment

​Traits and targeting

​SDK methods

​Next steps

What a company contains

Company ID vs. external ID

Creating companies

Wallet uniqueness

Plan assignment

Traits and targeting

SDK methods

Next steps