Sync Accounts

Customers (accounts) are the root of everything Alguna bills: subscriptions, usage, invoices and payments all hang off one. Before you can quote, subscribe or meter anyone, their customer record has to exist, and it has to be linkable to the record your own systems know. This page covers the three ways to create customers — automatically from a connected integration, programmatically through the API, or manually in the dashboard — and the alias mechanism that ties them to your identifiers. Use it during migration and again whenever a new system comes online. The object model is in How Alguna works.

From an integration
Via the API
In the dashboard

Sync accounts from a connected system

Connected integrations can import existing customers when you first connect them and keep them in step afterwards:

Salesforce and HubSpot — accounts and companies, with sync direction per object type set in External sync
Stripe — customers, their stored payment methods, and subscriptions
QuickBooks and Xero — customers

Each import stores the source system’s record ID on the Alguna customer, so the two stay matched even when names or emails change. If your customers live somewhere without a connector, use the API below or contact us.

Create customers with the API

Create each customer with POST /customers, passing your own identifier in aliases:

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" \
  -H "Idempotency-Key: import-customer-4821" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "aliases": ["4821"],
    "contacts": [{ "email": "billing@acme.com", "is_primary": true }]
  }'

import os

import requests

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

for row in [{"id": "4821", "name": "Acme Corp", "email": "billing@acme.com"}]:
    response = requests.post(
        "https://api.alguna.io/customers",
        headers={**HEADERS, "Idempotency-Key": f"import-customer-{row['id']}"},
        json={
            "name": row["name"],
            "currency": "USD",
            "aliases": [row["id"]],
            "contacts": [{"email": row["email"], "is_primary": True}],
        },
        timeout=10,
    )
    response.raise_for_status()

const customer = await alguna.customers.create(
  {
    name: "Acme Corp",
    currency: "USD",
    aliases: ["4821"],
    contacts: [{ email: "billing@acme.com", is_primary: true }],
  },
  { idempotencyKey: "import-customer-4821" },
);

The Idempotency-Key makes the import safe to re-run. Add a billing_address for tax and invoicing; update later with Update a customer.

External IDs (aliases)

An alias is any string that identifies a customer in one of your systems — your internal user or organization ID, a CRM record ID, a Stripe customer ID, an email. A customer can carry several. Once set, an alias works anywhere the API takes a customer:

account on usage events — send "account": "4821" instead of the Alguna ID
customer_alias on checkout sessions and portal sessions
GET /customers/lookup?alias=… to resolve an alias, or a connected account’s external ID such as a Stripe cus_…, to the Alguna customer ID

That means you never have to store Alguna IDs in your own database or CRM. Add aliases at creation or with Update a customer; connected integrations add theirs automatically.

Migration checklist — the customer fields to have ready
Customer management — contacts, addresses, tax details and families
Developer quick start — from a customer to a metered, invoiced subscription

Migrations

Sync accounts from a connected system

Create customers with the API

Create customers manually

External IDs (aliases)

Next

​Sync accounts from a connected system

​Create customers with the API

​Create customers manually

​External IDs (aliases)

​Next

Sync accounts from a connected system

Create customers with the API

Create customers manually

External IDs (aliases)

Next