End-to-end: invoice to payment

This is the shortest production flow: one request creates or finds the customer, creates the invoice, issues it and sends it. A signed event tells you when it is paid.

1. Create, issue and send

Use your order id as both externalReference and the basis of the idempotency key. A network retry can then never create a second invoice.

curl -X POST "https://api.rieckflow.com/v1/invoices?issue=true&send=true" \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: invoice-order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "type": "company",
      "name": "Acme ApS",
      "cvr": "12345678",
      "email": "ap@acme.example",
      "externalReference": "customer-9001"
    },
    "lines": [{
      "description": "Consulting",
      "quantity": 1,
      "unitPriceOere": 125000,
      "vatRateBps": 2500
    }],
    "dueDate": "2026-08-18",
    "externalReference": "order-2041"
  }'

The 201 response contains the issued invoice. Store data.id; use the externalReference for reconciliation in your own system.

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "invoiceNumber": 1042,
    "type": "invoice",
    "status": "issued",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "issuedDate": "2026-08-04",
    "dueDate": "2026-08-18",
    "grossOere": 156250,
    "paidOere": 0,
    "balanceOere": 156250,
    "externalReference": "order-2041"
  },
  "meta": {
    "send": { "outcome": "queued" }
  }
}

The invoice remains valid even if e-mail delivery fails. Inspect meta.send and retry POST /v1/invoices/{id}/send with a new logical-operation key after correcting the customer e-mail.

2. Receive the payment event

Subscribe to invoice.paid and payment.received. Deduplicate on webhook-id, then fetch the invoice before changing access or fulfilment in your system.

{
  "id": "evt_01J4E4Z5N6YV8E3C0KX4B7QW9M",
  "type": "invoice.paid",
  "tidsstempel": "2026-08-08T12:05:44Z",
  "organisationId": "f38d6d63-a127-45a8-8efd-02cd1239578f",
  "sag": null,
  "invoice": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "sekvensnummer": 4
  },
  "customer": null,
  "subscription": null,
  "data": {
    "invoiceNumber": 1042,
    "grossOere": 156250,
    "paidOere": 156250,
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "externalReference": "order-2041"
  }
}

3. Reconcile against the source of truth

curl https://api.rieckflow.com/v1/invoices/9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440 \
  -H "Authorization: Bearer $RIECK_API_KEY"

Treat the event as a signal and GET /v1/invoices/{id} as the truth. Mark the order paid only when data.balanceOere is 0. This also handles partial payments and credits.