Billing

Deliver an organization's approved invoices through your ERP or invoicing platform, and report each outcome back.

The billing API is for an invoicing connector: an app that connects an organization to its ERP or invoicing platform. Hydda One builds the invoices, and an operator approves them. Your connector handles each approved invoice. It delivers the invoice, collects payment, and books it in the customer’s own system.

Your connector does all the calling. Hydda One never calls it. The connector reads work from queues and reports each outcome on its own route.

What the token needs

The caller is an installed connector, with a token from the installation-token grant. See Authentication.

The installation must hold the Billing Integration role at the organization. Hydda One grants it when an administrator saves the connector’s configuration at the organization. An organization has one invoicing connector at a time. See Roles.

The queues stay closed until the connector reports that configuration ready. Until then, the queues and reports answer BILLING_INTEGRATION_NOT_CONFIGURED. See Integrations for how to report it.

A token without an organization answers 403.

Gates

The connector’s manifest declares which parts of the invoicing it handles. Hydda One calls these parts gates.

A route for a gate the connector did not declare answers BILLING_INTEGRATION_GATE_NOT_DECLARED. It never answers an empty queue instead.

The flow

Each call is described in the billing reference.

1. Verify the proposals. Only with the basisVerification gate. Poll GET /v1/billing/verification-queue. For each proposal, call pass with your externalReference, or reject with a reason. A pass answers with the proposal and the invoice it became. The invoice carries your reference. It reaches the send queue once an operator approves it.
2. Send the invoices. Poll GET /v1/billing/send-queue. It lists approved invoices whose requested invoice date has come, oldest approval first. “Today” is the current calendar day in UTC. Issue each invoice in your ERP. Then call report-sent, or report-failed with a reason.
3. Report payments. Call report-payment once for each payment your platform receives. Call report-payment-reversed when a payment is taken back. Both routes also exist under /v1/billing/invoices/by-external-reference/{ref}/, addressed by your own reference.
4. Report write-offs. Call report-write-off when your platform gives up collecting an amount. It is addressed by the invoice id only.
5. Discard deleted invoices. Poll GET /v1/billing/withdrawal-queue. It lists invoices an operator deleted after you attached your reference to them. Discard your copy, then call report-discarded.

What report-sent carries

report-sent brings back what your ERP issued. Your ERP decides the legal invoice, so Hydda One records what it issued.

If the invoice came from a proposal you passed, it already carries your reference. externalReference must then match it.

Which company an invoice belongs to

One connector serves the whole organization. The organization can run several companies, each with its own ERP account.

Every queue item names businessContextId. It is the business that owns the invoice’s contract. Use the credentials of your configuration at that business. When that business has no configuration, use the organization’s configuration. See Integrations.

businessContextId is null when Hydda One does not know the business. Do not guess a company. Report the invoice failed instead.

What an item carries

An item carries the invoice or proposal, its lines in position order, and its VAT subtotals. The recipient block holds the customer’s name, type, identifiers, invoice address and delivery method. Every field is frozen when the document is written, so two reads of one item always agree.

Issue the invoice with requestedInvoiceDate and requestedDueDate as they stand. Do not compute other dates.

A credit note rides the same queues. Its documentKind is credit-note, and creditedInvoiceId names the invoice it credits. Its totals are negative, and it is settled with a negative payment.

An identifier with the scheme se-personnummer or se-samordningsnummer is personal data. Keep it out of your logs.

Statuses

An invoice moves through these statuses on this API:

The balance is the issued total, less every payment that was not reversed and every write-off. The invoice becomes paid when the balance reaches zero or goes past it. An overpayment is accepted. If any write-off counted, it becomes written-off instead. A partial payment or write-off leaves it sent.

A proposal is proposed until you pass or reject it. It never expires. Only an operator can cancel it.

Rules for callers

A queue is not consumed by reading it

Reading a queue claims nothing. An item stays on its queue until a report changes its status. If your connector crashes, poll again and you get the same items.

Work can therefore arrive twice. Your connector may reach your ERP and fail before it reports. It then gets the item again. Check your own reference before you issue a document a second time.

An item you cannot act on leaves the queue only when you report it failed. Nothing else clears it.

What a repeated report does

platformPaymentId and platformWriteOffId are your payment platform’s own ids, 1 to 200 characters. They make the payment and write-off reports safe to repeat.

Amounts

A payment or write-off amount is never zero. Its sign must match the sign of the issued total. A refund on a credit note is a negative payment.

Hydda One accepts payments on a sent, paid or written-off invoice. A write-off cannot be undone, and there is no route for it.

Limits

The queues have no cursor. You empty a queue by reporting on its items. A request over the rate limit gets 429.

Errors to handle

A 404 without a code means the invoice or proposal does not exist, or belongs to another organization.

Errors lists every billing code and its status.