Manage Customers

A customer is the account you bill: a company or person with a name, a billing currency, an address, contacts, tax settings and any identifiers you use for them elsewhere. Every subscription, invoice, wallet and entitlement hangs off a customer, so it is the first thing to create for a new account. Customers can be grouped into families for consolidated billing and are billed from one of your legal entities. See How Alguna Works for the object graph.

Dashboard: Production or Sandbox. To bulk-import customers or sync them from a CRM or payment processor, see Sync accounts.

Create a customer via the API

Create a customer (POST /customers) needs a name and a currency; everything else is optional. Set aliases to the IDs your own systems use for this customer, so you can address them by those IDs later without storing Alguna’s.

curl -X POST https://api.alguna.io/customers \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "aliases": ["acme-prod-42"],
    "billing_address": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "USA"
    },
    "contacts": [
      {
        "email": "finance@acme.example",
        "first_name": "Accounts",
        "last_name": "Payable",
        "is_primary": true,
        "email_preferences": ["billing"]
      }
    ]
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.alguna.io/customers",
    headers=HEADERS,
    json={
        "name": "Acme Corp",
        "currency": "USD",
        "aliases": ["acme-prod-42"],
        "billing_address": {
            "line1": "123 Main St",
            "line2": "Suite 100",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "USA",
        },
        "contacts": [
            {
                "email": "finance@acme.example",
                "first_name": "Accounts",
                "last_name": "Payable",
                "is_primary": True,
                "email_preferences": ["billing"],
            }
        ],
    },
    timeout=10,
)
response.raise_for_status()
customer = response.json()
print(customer["id"])

billing_address.country is an ISO 3166-1 alpha-3 code (USA, DEU, GBR). currency is ISO 4217.

Addressing a customer by your own ID

Wherever an endpoint takes a customer {id}, it also accepts an alias or a connected-account external ID (for example a Stripe customer ID). To resolve one to the Alguna ID without fetching the whole record, use Look up a customer ID by alias (GET /customers/lookup?alias=...).

Create or look up?

There is no upsert endpoint: POST /customers always creates, and calling it twice for the same buyer gives you two customers with split subscriptions, usage and invoices. When your signup flow cannot be sure whether the customer already exists, look up first and create only on a miss:

GET /customers/lookup?alias=<your ID> — a 200 returns the Alguna ID and you are done.
On 404, POST /customers with that same ID in aliases.
Send an Idempotency-Key on the create, derived from your own ID (for example ik_customer_<your ID>), so a retry after a timeout replays the first response instead of creating a second customer.

The alias is what makes this work, so set it on creation rather than adding it later — a customer created without one cannot be found by your ID on the next attempt. Two concurrent signups for the same buyer are the case the idempotency key covers; the lookup alone does not. If the customer originates in a connected system rather than in your own product, prefer the paths built for that: Sync accounts for a bulk import, or the CRM integrations to create the customer from a company record.

Update

Update a customer (PATCH /customers/{id}) patches only the fields you send. Sending contacts or aliases replaces the whole list, so include the existing entries you want to keep. Tax settings, legal entity and parent customer are set in the dashboard; the API returns tax fields read-only on the customer.

Connected accounts

If the customer also exists in a connected system (Stripe, HubSpot, an accounting integration), record the link with Link a connected account to a customer (POST /customers/{id}/connected-accounts, with integration_id and external_id). This records the mapping only; it creates nothing in the external system and triggers no sync.

Create a customer in the dashboard

In Customers, click New Customer.

New Customer dialog with name, primary contact email, country, billing currency, address, tax rate, external identifiers and legal entity

Customer information

Customer name: the company or person you are billing.
Primary contact email, first name and last name: the contact that receives correspondence by default.

Location

Country and billing currency (ISO 4217).
Address (optional): line 1, line 2, city, state, postal code.

Tax — a customer-level tax rate (defaults to 0.00%). When a tax provider or Alguna Tax is configured, tax is determined by rules and this is managed for you. See Customer Tax Rates. External IDs — aliases from your own systems, used to address the customer through the API and to attribute usage events. See Send usage. Legal entity — which of your legal entities bills this customer. See below. Parent customer (optional) — makes this customer a child of another for consolidated billing.

Editing a customer

The Customer Profile page groups the customer’s settings:

Section	What it holds
Business information	Business name; billing currency; which invoicing flow applies; payment terms such as Net 30 (see Invoicing configuration); whether auto-pay is on
Billing address	Country, address lines, city, state, postal code. Used on invoices and for tax determination
Tax settings	Tax country, tax ID, tax rate, tax reason and tax type. See Customer Tax Rates
External identifiers (aliases)	Your IDs for this customer. Connected-account IDs act as aliases automatically
Contacts	Who receives which emails. See Customer Contacts
Payment methods	Stored cards and bank accounts collected through checkout or the portal

Legal entities and merchants

Two different things sit above a customer, and they are easy to confuse:

A legal entity is one of your selling entities: the registered business that issues the invoice, holds the tax registration and owns the receivable. Configure them under Settings → Legal Entities; each has its own tax rules and FX rates. Every customer is assigned to one legal entity, and that entity appears as the From party on the customer’s invoices. Revenue and tax reporting are available per legal entity (GET /revenue-schedules/legal-entity/{id}). See Alguna Tax and Multi-currency.
A merchant is a business you sell on behalf of. Invoices and receipts issued for a merchant carry its name and logo, while your legal entity stays the seller of record and keeps the contract, the payment and the tax liability. Merchants are display identity only and are managed through the Merchants API (POST /merchants with a display_name and your external_id, optional logo and support email).

If you bill from more than one country or entity, set up a legal entity per jurisdiction first and assign customers to the right one; the invoice, tax treatment and revenue schedule all follow that assignment.

Next steps

Customer Contacts

Route invoices, quotes and updates to the right people.

Customer Tax Rates

Tax ID, rate and treatment per customer.

Customer Families

Parent and child customers for roll-up billing.

Create your first subscription

Put the customer on a plan.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Create a customer via the API

Addressing a customer by your own ID

Create or look up?

Update

Connected accounts

Create a customer in the dashboard

Editing a customer

Legal entities and merchants

Next steps

Customer Contacts

Customer Tax Rates

Customer Families

Create your first subscription

​Create a customer via the API

​Addressing a customer by your own ID

​Create or look up?

​Update

​Connected accounts

​Create a customer in the dashboard

​Editing a customer

​Legal entities and merchants

​Next steps

Customer Contacts

Customer Tax Rates

Customer Families

Create your first subscription

Create a customer via the API

Addressing a customer by your own ID

Create or look up?

Update

Connected accounts

Create a customer in the dashboard

Editing a customer

Legal entities and merchants

Next steps