The Company object

A company in ArcenPay represents one of your customers. It holds identity fields (name, wallet, email), an optional external ID from your own system, plan assignment, feature entitlements, and a list of associated users. Most billing and entitlement operations resolve against a company, so syncing your customer records with ArcenPay is a foundational step in any integration.

Company object

{
  "id": "cm_abc123",
  "name": "Acme Corp",
  "walletAddress": "0xabc...",
  "email": "[email protected]",
  "externalId": "company_123",
  "logoUrl": null,
  "traits": { "industry": "fintech" },
  "activePlan": {
    "id": "plan_starter",
    "name": "Starter",
    "tier": 1,
    "price": 49,
    "billingInterval": "MONTHLY"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "lastSeenAt": "2024-06-01T12:00:00.000Z"
}

Company ID vs. external ID

ArcenPay assigns every company an internal ID with the cm_... prefix. This is separate from the externalId field, which holds the ID from your own system (whatever you pass as id when creating or identifying the company). Most API calls that look up a company — such as GET /api/v1/companies/:id — accept the ArcenPay internal ID. Entitlement checks and access-token minting accept either the external ID, wallet, or email for resolution.

string

ArcenPay’s internal company ID, prefixed cm_....

string | null

Your system’s ID for this company, set via the id field at creation time.

string

Display name for the company.

string | null

Wallet address associated with this company. EVM addresses are stored lowercased; Stellar (G…/C…) and Solana (base58) addresses are stored exactly as signed.

string | null

Billing or contact email for this company.

object | null

The currently assigned catalog plan, or null if no plan is active.

object

Arbitrary key-value metadata. Use this to store attributes from your own system.

array

Resolved entitlements for this company, returned from GET /api/v1/companies/:id. Each entry contains featureKey, value, reason, allocation, usage, and exceeded.

List companies

GET /api/v1/companies returns a paginated list of companies in your team, ordered by most recently seen.

GET /api/v1/companies?limit=50&cursor=cm_abc&search=acme
Authorization: Bearer sk_live_xxxxxxxx

number

Number of results to return. Defaults to 50, maximum 200.

string

Pagination cursor from the previous response’s nextCursor. Must be a non-empty string.

string

Case-insensitive search across name, email, and wallet address.

Response:

{
  "data": [...],
  "count": 50,
  "nextCursor": "cm_xyz789"
}

Get a company

GET /api/v1/companies/:id returns full company detail including active plan, entitlements, add-on grants, users, and overrides.

GET /api/v1/companies/:id
Authorization: Bearer sk_live_xxxxxxxx

The :id parameter is the ArcenPay internal cm_... company ID.

Create a company

POST /api/v1/companies creates a new company record.

POST /api/v1/companies
Authorization: Bearer sk_live_xxxxxxxx
Content-Type: application/json

string

required

Display name for the company. Maximum 128 characters.

string

Your system’s external company ID. Stored as externalId. Maximum 64 characters.

string

Wallet address: EVM 20-byte hex (0x...), Stellar (G... account or C... contract), or Solana base58. Returns 409 if another company in your team already has this wallet.

string

Company email address. Maximum 254 characters, must be a valid email format.

object

Arbitrary key-value metadata. Must be a plain object (not an array).

string

URL for the company’s logo.

Example:

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

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

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

A successful response returns 201 with { "data": { ...company } }.

If you pass a wallet that already belongs to another company in your team, the endpoint returns 409 with the conflicting companyId so you can resolve the mapping.

Update a company

PATCH /api/v1/companies/:id updates the company’s name, traits, active plan assignment, or add-on IDs. All fields are optional — only the fields you include are updated.

PATCH /api/v1/companies/:id
Authorization: Bearer sk_live_xxxxxxxx
Content-Type: application/json

string

New display name. Maximum 128 characters.

object

Traits to merge into the existing traits object. Existing keys not included in this update are preserved.

string | null

Assign or unassign the active catalog plan. Pass null to remove the plan assignment.

string[]

Replace the full list of active add-on IDs for the company.

Example:

await client.updateCompany("cm_abc123", {
  name: "Acme Corp (renamed)",
  traits: { tier: "enterprise" },
});

Delete a company (dashboard only)

DELETE /api/v1/companies/:id permanently removes a company and its associated data. This is a dashboard-managed operation — ArcenClient does not expose it, and it should not be scripted from your application. Remove customers from Customers → Companies in the dashboard (requires a catalog:write session role). Returns { "ok": true } on success. Returns 404 if the company does not exist in your team.

Deletion is permanent and cannot be undone. Associated subscription state, entitlements, and user records are removed along with the company record. Do not attempt to call this endpoint with an API key — it requires a dashboard session.

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Invoices

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

The Company object

Company object

Company ID vs. external ID

List companies

Get a company

Create a company

Update a company

Delete a company (dashboard only)

​Company object

​Company ID vs. external ID

​List companies

​Get a company

​Create a company

​Update a company

​Delete a company (dashboard only)

Company object

Company ID vs. external ID

List companies

Get a company

Create a company

Update a company

Delete a company (dashboard only)