Create customers, plans, and subscriptions through the API
The API lets an external system keep Alunta's core records synchronized. Work with the objects in their natural order: create or find the customer, create a plan with valid prices and intervals, then create the subscription.
Historical retrospective - November 2025 to April 2026
This article was written afterwards and brings together the documented expansion of API resources.
The API lets an external system keep Alunta’s core records synchronized. Work with the objects in their natural order: create or find the customer, create a plan with valid prices and intervals, then create the subscription.
Use the team’s personal token from Settings → API for these calls. Partner OAuth is a separate authorization path for partner integrations and does not change how the team’s API token is created or revoked.
Customers and stable mappings
Create a customer with a name; it is the only required field in the OpenAPI contract. Email, phone, address, ZIP code, city, and country are optional. If you send country, use an uppercase ISO 3166-1 alpha-2 code such as DK; when omitted, the contract defaults it to the team’s country. An optional external_customer_id can contain your system’s reference. Store both the external reference and Alunta’s UUID; they solve different problems. Do not reuse an external reference for multiple customers without an explicit mapping rule.
Plans and intervals
Read the plan’s pricing_type first. For a regular plan, fetch its renewal intervals and use a valid renewal_interval_uuid. A tiered plan has no renewal-interval rows in that collection; use the tier price’s documented interval and currency together with the tier inputs required for creation. Always ensure price, currency, pricing type, and payment provider fit together. A plan is a reusable description of what is sold. It is not the same as a customer’s effective price or start date.
The subscription
Once the customer and plan are ready, create the subscription with the plan UUID, customer UUID, and either a renewal-interval UUID or the tiered interval/currency pair offered by the plan. A synthetic tiered example can use the fictional, nonexistent UUIDs {"plan_uuid":"00000000-0000-4000-8000-000000000002","customer_uuid":"00000000-0000-4000-8000-000000000001","interval":1,"currency":"DKK"}; use the current OpenAPI schema for exact field names and any subsequent tier endpoints. The response is the stable source for the subscription UUID and status. Read it again after creation if the integration needs to show the start date, price, or payment details.
Bank accounts can be created, updated, read, and deleted through the documented bank-account endpoints. This keeps an external admin or ERP interface synchronized; creating a bank account does not move money or automatically change an invoice’s payment status.
Errors and boundaries
422 can mean that a country code, currency, interval, or payment provider does not fit the request. A missing interval is not a reason for the client to invent an alternative. Read pagination, field names, and statuses from OpenAPI, and handle amounts in the unit documented by the relevant schema.
See the public API and webhooks guide (Markdown file, AI agent-friendly) for the current sequence and synthetic UUID examples.
A complete example
An external sales system can first send a customer with external_customer_id: "crm_demo_42", store the returned UUID, and then fetch the plan’s renewal intervals. If the plan has a EUR price for 12 months, the client must not create the subscription with DKK or an interval the plan does not offer. After creation, store the subscription UUID and read its status back. A later webhook can then be linked to both the external customer ID and Alunta’s own references.
If a customer already exists, the integration should use its own unique mapping or search the documented identity before creating another. The API should not deduplicate by name alone. If a bank account is deleted, the client should also check the current standard-account and usage rules; bank-account CRUD is not a payment command.
Why is an interval missing? On a regular plan, a valid renewal-interval price is missing. On a tiered plan, an empty renewal-interval collection is expected; read tier prices and use interval plus currency.
Can I change a plan without changing every subscription? A plan catalog and an existing subscription are different; read the endpoint description and subscription response.
What should I do with 422? Show the field error, correct the invalid combination, and resend the same business intention only after the input is valid.
The people and AI helpers behind the updates
Bo Møller and Emil Højbjerg are the primary developers behind Alunta. They spend most of their time coding, so they have delegated the wording of these explanations to our AI helpers.
The AI helpers write from the updates we have deployed to the product. Bo and Emil are behind the changes and remain responsible for ensuring the information reflects what was actually released.
