Rechnungskit API

Quickstart

One key, two scopes

Create a project-bound key under Connections → API in the app. The full key is shown exactly once and belongs only in your backend or secret manager.

Integration flow

Your own order number links every step

You never need an internal Rechnungskit ID. Use an orderNo that stays unique for good. If the customer pays through Stripe, Mollie or another provider, also send that provider's unique paymentRef.

1. 1
   Send the order

   Your orderNo becomes the stable key that links everything.

2. 2
   Payment or fulfillment

   The payment webhook is matched on paymentRef. Only physical goods (requiresShipping: true) wait for fulfillment. SaaS and digital services skip this step, and the invoice is created as soon as the payment arrives.

3. 3
   Check the status

   GET /v1/orders/{orderNo} returns the invoices linked to the order.

4. 4
   Store the exact invoice ID

   Save the returned invoice UUID or invoice number for this document.

5. 5
   Download the document

   PDF and XML stay behind Bearer auth, so your server fetches them.

1 · Order

Send the order idempotently

Every POST needs a stable Idempotency-Key. After a timeout, you can repeat the same request with the same key without creating a second order.

curl https://api.rechnungskit.de/v1/orders \
  -X POST \
  -H "Authorization: Bearer $RK_API_KEY" \
  -H "Idempotency-Key: order:CM-10482:v1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNo": "CM-10482",
    "paymentRef": "pi_3PqK8w2eZvKYlo2C",
    "currency": "EUR",
    "requiresShipping": false,
    "billingAddress": {
      "name": "Lisa Brandt",
      "street": "Torstraße 99",
      "postal_code": "10119",
      "city": "Berlin",
      "country_code": "DE"
    },
    "service_period": {
      "start_date": "2026-06-01",
      "end_date": "2026-06-30"
    },
    "items": [{
      "name": "Monatsabo Pro · Juni 2026",
      "sku": "saas-pro",
      "quantity": 1,
      "unitNetCents": 4118,
      "discountNetCents": 500,
      "taxRate": 19
    }]
  }'

{
  "data": {
    "id": "6d754aec-40d9-4c1a-a78c-50dbb6c8e307",
    "orderNo": "CM-10482",
    "status": "created"
  },
  "requestId": "9d61558e-3c00-465d-b980-c074db600047"
}

Required fields

Optional fields

2 · Fulfillment

Report shipping or service delivery

For physical goods, the shipping date is the date of supply that counts. So report the complete shipment. Partial fulfillments do not produce a complete invoice yet.

curl https://api.rechnungskit.de/v1/fulfillments \
  -X POST \
  -H "Authorization: Bearer $RK_API_KEY" \
  -H "Idempotency-Key: fulfillment:CM-10482:fulfilled:v1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNo": "CM-10482",
    "status": "fulfilled",
    "shippedAt": "2026-07-27T10:30:00Z",
    "trackingNumber": "003404341612"
  }'

3 · Status & documents

How to get the invoice ID

Ask for the status with your own order number. Once an invoice exists, invoices[] contains its UUID, invoice number and archive status.

curl https://api.rechnungskit.de/v1/orders/CM-10482 \
  -H "Authorization: Bearer $RK_API_KEY"

{
  "data": {
    "orderNo": "CM-10482",
    "status": "invoiced",
    "fulfillmentStatus": "fulfilled",
    "invoices": [{
      "id": "f77ba43d-6f06-4b84-bd24-5cfab76a1192",
      "number": "RK-2026-0148",
      "status": "archived",
      "url": "/v1/invoices/f77ba43d-6f06-4b84-bd24-5cfab76a1192"
    }]
  },
  "requestId": "3a61c30d-4386-4c60-9354-841342cbc372"
}

Then use the UUID whenever you want to download one specific document. It stays unambiguous after a cancellation or when an order has several documents.

curl https://api.rechnungskit.de/v1/invoices/f77ba43d-6f06-4b84-bd24-5cfab76a1192/pdf \
  -H "Authorization: Bearer $RK_API_KEY" \
  --output RK-2026-0148.pdf

Alternative · Pay by invoice

Invoice first, payment later

When a customer buys on invoice, there is no provider payment at first. Instead, send the gateway name you approved in Rechnungskit under Connect. Once fulfillment is complete, the invoice is created as an open item with a payment term.

{
  "orderNo": "CM-10483",
  "paymentGateway": "invoice",
  "financialStatus": "pending",
  "requiresShipping": true,
  "billingAddress": { "...": "full billing address" },
  "items": [ "..." ]
}

Store credit · Push

Report referral and customer credit

If your application manages credit itself, for example referral rewards, send every movement to POST /v1/credit-transactions: earning (earn), redeeming (redeem), reversal (reverse), payout (payout) and expiry (expire). Each transaction carries your unique id, so repeating a call never creates anything twice. Up to 500 per call.

{
  "transactions": [
    {
      "id": "tx_81",
      "type": "earn",
      "email": "kundin@example.com",
      "amount_cents": 500,
      "occurred_at": "2026-10-02T09:14:00+02:00",
      "order_ref": "103002"
    },
    {
      "id": "tx_82",
      "type": "redeem",
      "email": "kundin@example.com",
      "amount_cents": 500,
      "occurred_at": "2026-10-05T18:40:00+02:00",
      "order_ref": "103950"
    }
  ]
}

{ "accepted": 2, "duplicates": 0, "applied": 1 }

Once a day, report the balance per customer to PUT /v1/credit-balances ({ "balances": [{ "email": "…", "balance_cents": 1250 }] }). Rechnungskit compares them with the history and creates a task when a customer's balance differs. That way, a lost message gets noticed too.

Reference

API v1 endpoints

Machine-readable reference: Download OpenAPI 3.1 ↗

Errors & retries

Every response carries a request ID

The X-Request-Id header and the JSON field requestId identify the same request. You can find it in your project's API activity for 30 days.

{
  "error": {
    "code": "validation_failed",
    "message": "billingAddress.country_code is required for VAT determination",
    "field": "billingAddress.country_code"
  },
  "requestId": "9d61558e-3c00-465d-b980-c074db600047"
}

Sandbox

Test first, then go live

Every account starts in test mode, with the same API, the same pipeline and the same rk_key_… key as in production, including EN 16931 validation and PDF/A-3 rendering. So you test exactly the behavior that runs live later, with the key that also works live.

Security

Secrets stay in the backend

• Never put API keys into browser code, mobile apps or a public repository.
• Store keys in a secret manager or in encrypted environment variables.
• Rotate production keys without an expiry date on a schedule you choose; use short-lived keys only for tests or transitions.
• Review keys that have not been used for more than 90 days in the API settings, and revoke them when the integration is no longer needed.
• If you suspect a key has leaked, create a new one right away, roll it out and revoke the old one.
• Fetch documents on your server; never give customers permanent Bearer links.