Skip to content
Help support@rechnungskit.de
Topics: API

Connect your own application via API

With the Rechnungskit REST API, your SaaS, checkout or platform reports orders, fulfillments, cancellations and credit movements. Keys, endpoints, service periods, idempotency and retries explained.

Updated

With the REST API, your own application (SaaS, your own checkout, a platform) reports transactions to Rechnungskit. This page covers keys, endpoints, the most important fields and what to watch for when you send data. The full reference is in the API reference.

The flow in short: your application sends the order. The payment comes from the connected payment provider, and as soon as the two match, Rechnungskit creates the document. For goods, the invoice also waits for your shipment report.

REST API · flow
From API order to e-invoice
Your application
POST /v1/ordersline items and amounts in cents, optional paymentRef
POST /v1/fulfillmentsonly for physical goods, sets the date of supply
Rechnungskit
  1. Accepts the orderidempotent through your orderNo
  2. Matches the paymentfrom the connected payment provider, paymentRef speeds this up
  3. Creates the documentwith EN 16931 validation and PDF
Result
E-invoiceZUGFeRD, with a valid Leitweg-ID as XRechnung 3.0
Fetch via APIstatus through GET /v1/orders/{orderNo}, PDF and XML through /v1/invoices
There is no "paid" field: the payment status comes from the payment provider. The only exception is an order paid entirely with referral credit.

Basics

Item How it works
Base URL https://api.rechnungskit.de/v1
Format REST with JSON, OpenAPI 3.1
Authentication bearer token with your API key
Amounts always integer cents, never decimals
Idempotency Your order number (orderNo) is the natural key, and the Idempotency-Key header is supported as well. Duplicate submissions never create duplicate documents.

API keys

You create keys under Settings → Connections → API. There are two permissions:

Permission What for
orders:write report orders, cancellations and fulfillments, send credit movements and balances
invoices:read fetch documents, including the state of an order through GET /v1/orders/{orderNo}
subscriptions:write create customer portal links for a subscription. Not preselected when you create a key, because such a link lets its holder end the contract

There is ONE key type (prefix rk_key_). Whether documents are test data or real depends only on the project's test mode, never on the key. The same key creates test documents in test mode and real documents after go-live, so nothing has to be swapped. Older keys with the prefix rk_test_ or rk_live_ stay valid unchanged.

  • Shown once: the full key is shown exactly once, after that only its beginning.
  • Expiry: your choice of 30, 90 or 365 days or no expiry.
  • Unused: keys not used for more than 90 days are flagged.

Main endpoints

Endpoint What for Permission
POST /v1/orders submit an order (line items, amounts in cents, payment method) orders:write
GET /v1/orders/{orderNo} state of an order with all its documents invoices:read
POST /v1/orders/{orderNo}/cancel report a canceled order (see below) orders:write
POST /v1/fulfillments report shipment (sets the Leistungsdatum, the date of supply), only needed for physical goods orders:write
POST /v1/checkout-links one-time link to the subscription checkout, with the email pre-filled and your metadata (see below) orders:write
POST /v1/subscriptions/{id}/portal-links short-lived customer portal link for one subscription (see below) subscriptions:write
GET /v1/invoices list documents invoices:read
GET /v1/invoices/{reference} fetch one document invoices:read
GET /v1/invoices/{reference}/pdf and /xml download document files invoices:read

Example order

POST https://api.rechnungskit.de/v1/orders
Authorization: Bearer rk_key_…

{
  "orderNo": "CM-10482",
  "email": "kunde@example.com",
  "paymentRef": "pi_123",
  "requiresShipping": true,
  "shippingGrossCents": 490,
  "billingAddress": { "name": "Erika Muster", "country_code": "DE" },
  "items": [
    { "name": "Kaffee 1kg", "quantity": 2, "unitGrossCents": 2490, "taxRate": 7, "productId": "bohne-42" }
  ]
}

Required are orderNo, billingAddress with country_code and at least one line item with name, quantity and unitNetCents or unitGrossCents.

unitNetCents is the net price, unitGrossCents the gross price. taxRate is optional: without it, Rechnungskit takes the rate from the product and adds the VAT on top of unitNetCents, or takes it out of unitGrossCents.

Shipping costs

You send shipping costs in one of two ways:

  • shippingGrossCents: the gross amount paid. Rechnungskit works out the tax itself.
  • shippingNetCents plus shippingTaxRate: when your checkout has already calculated the shipping tax.

If the cart has mixed tax rates, Rechnungskit splits the shipping automatically by the gross value of the goods (BFH, judgment of 22.01.2025, XI R 22/22: split by gross selling prices), just as in the Rechnungskit checkout. The amount paid never changes.

Fetching an order's documents

GET /v1/orders/{orderNo} returns for each document:

  • the type (invoice, correction, voucher_receipt) and the document kind,
  • the reference to the corrected invoice (referencedInvoiceId),
  • date, gross amount and PDF link.

What GET /v1/invoices/{reference} returns depends on what you ask with:

You ask with You get
UUID or document number exactly that document
order number or payment reference the order's invoice, even if a cancellation invoice (Storno) exists by now
Stripe invoice ID (in_…) the invoice for that Stripe invoice, when you take over from Stripe Billing

You fetch the cancellation invoice by its UUID. For orders you send through the API, it is listed in GET /v1/orders/{orderNo}. For orders from a shop connection (WooCommerce, Shopify, Shopware …), use GET /v1/invoices?orderNo={orderNo}: the list holds every document of the order, newest first. type says what it is (invoice, correction for the cancellation invoice, voucher_receipt), and documents.pdf is its PDF link (fetch it with your API key). One page holds up to 100 documents (limit=100, default 25). If pagination.hasMore is true, fetch the next page with cursor={pagination.nextCursor}.

Your own references: metadata

With metadata you give an order your own identifiers, such as the ID of the Stripe invoice, your customer or your contract. Rechnungskit returns them with every document of that order. That way you can map a Rechnungskit invoice to your own record without your internal IDs appearing as the order number on the invoice.

"metadata": { "stripe_invoice": "in_1QxExample", "customer": "cus_42" }
  • Up to 20 entries, text only. A name has at most 40 characters, a value at most 500. Otherwise the API answers 422 and names the field.
  • metadata never appears on the invoice or in the e-invoice (XML).
  • It comes back in GET /v1/orders/{orderNo} as metadata, in GET /v1/invoices and GET /v1/invoices/{reference} as references.metadata, and in the invoice.paid webhook under order.metadata. Orders from a shop connection have null there. Orders from Stripe Billing already carry the Stripe invoice ID in references.stripeInvoiceId, so you don't need metadata for it.
  • If you send the order again, the metadata you sent last applies.
  • You cannot search by it. To look something up, use the order number or the payment reference.
  • Store only identifiers there, no names or email addresses.

Proforma invoice via the API

For an open order that is already in Rechnungskit, fetch the proforma invoice or send it with the payment request to your customer. This covers orders from shop connections (Odoo, Shopify, WooCommerce, Shopware), from the API and manual prepayment orders. Open means: not paid, not cancelled, no invoice yet. {reference} is the order's id or its order number.

  • GET /v1/proforma/{reference} returns the PDF as it would be sent now. Scope: invoices:read or orders:write.
  • POST /v1/proforma/{reference}/send emails it to the order's address. Scope: orders:write.
{
  "subject": "Your order S00042",
  "body": "Hello,\n\nplease transfer the amount and the licence goes out.",
  "attach": true,
  "whenReady": false
}

Every field is optional. Without subject and body, Rechnungskit uses the "Zahlungsaufforderung" template from Settings → Documents → Invoice e-mails; if you send them, send both. With "attach": false the email goes out without the PDF (default: with the PDF). Bank details, payment reference and the sentence that this is not an invoice are always added. A 200 response carries status (sent, or sent_test in test mode: the copy went to you) and version, the number of versions sent so far. Every sent email is in the order history with its PDF.

The proforma shows the gross amount and never a VAT amount or an invoice number, as described in Payment request and proforma invoice.

Customer elsewhere in the EU with a VAT ID and 0 %: without a positive qualified check you get 409 vat_check_pending. With "whenReady": true Rechnungskit answers 202 (status: queued) and sends the email once the check is positive. If it's negative (409 vat_check_failed), nothing goes out; the account owners get an email and the case shows up under Tasks.

Other errors: 404 order_not_found, 409 ambiguous_reference (the order number exists in two sources, use the id), 409 proforma_not_available (details.reason: paid, cancelled, invoiced, or not_vorkasse for checkout and subscription orders), 422 no_email, no_iban, no_identity.

When your customer is signed in to your software, your server requests the link to the subscription checkout instead of showing a fixed link:

POST /v1/checkout-links
{
  "plan": "abo-pro",
  "email": "customer@company.com",
  "metadata": { "workspace_id": "ws_42" },
  "returnUrl": "https://app.your-software.com/billing"
}
→ 201 { "data": { "id": "…", "url": "https://checkout.rechnungskit.de/s/abo-pro?t=…", "expiresAt": "…" } }
  • plan is the part after /s/ in the plan's subscription link (or the plan id).
  • The URL only contains a random token, no email and no metadata. The buyer can't change any of it.
  • The email is pre-filled in the checkout; the buyer can still change it.
  • metadata (up to 20 entries, text only) is stored on the subscription and comes back in every subscription.* webhook for its whole lifetime: renewals, upgrades, downgrades, quantity changes, cancellation and payment problems, including changes the buyer makes in the customer portal. That way your software always knows which workspace is meant. The API rejects names Rechnungskit uses itself (such as migrated_from).
  • returnUrl: after a successful purchase, the thank-you page redirects there, with ?subscription=<subscription id> appended (the same id as subscriptionId in the webhook). Without returnUrl, the plan's redirect applies: in the app under Products → Own products, on the product's subscription plan → "Nach dem Kauf weiterleiten zu" (redirect after purchase).
  • The link is valid for 24 hours (expiresInMinutes, 5 minutes to 7 days). Until the subscription is active it can be opened again, for example after a cancelled payment. After that, and after it expires, it shows a notice and, if set, a link back to returnUrl.
  • Your existing API key with orders:write is enough. The endpoint honours an Idempotency-Key, but doesn't require one here.

Never put the email as a parameter into the public subscription link: it would end up in browser history and server logs.

Businesses only

If your terms say you only sell to businesses, set the customers on the subscription plan to "Businesses only" (in the app under Products). The checkout then shows no "private individual" option, the company name is required, and buyers from other EU countries must enter their VAT ID. Rechnungskit also checks this on the server, so a modified request can't get around it. The setting applies to every new sign-up for the plan, with or without an API link. Existing subscriptions stay unchanged.

If your customer has an account with you, you can send them to their subscription in the customer portal without a second login. When they click a button on your side, your server requests the link and redirects them:

POST /v1/subscriptions/{id}/portal-links
{ "intent": "withdraw" }
→ 201 { "data": { "url": "https://konto.rechnungskit.de/subscription/…?s=…&intent=withdraw", "expiresAt": "…" } }
  • {id} is the subscriptionId from the subscription.* webhooks and the ?subscription= parameter on your returnUrl.
  • The key needs the subscriptions:write scope. Existing keys don't have it, so create a new one for this.
  • Request the link at the moment of the click, and only for a customer you have logged in yourself as the owner of this subscription. Whoever holds the link can end the contract.
  • Append &lang=en and the portal opens in English; without it, it opens in German.
  • The link works for 15 minutes (expiresInMinutes, 1 to 60). After that it shows "Link expired" and offers a new link by email.
  • Cancellation and withdrawal then happen in the customer portal. You can drop your own form, and subscription.canceled and subscription.withdrawn tell you the result.
Your button intent What your customer sees
Manage subscription none the whole subscription page
Cancel contracts here cancel only the confirmation with "Confirm cancellation"
Withdraw from contract withdraw only the withdrawal step with "Confirm withdrawal"

Once the withdrawal period has ended, withdraw opens the normal subscription page with a note saying so. There is no API that triggers a cancellation or withdrawal directly. The customer confirms both in the customer portal, and you record a withdrawal received by email or letter in the app. If in doubt, have a lawyer check whether your button and where you place it meet § 312k BGB and § 356a BGB.

Item ID per line: productId

Each line item may carry a productId, the stable item ID from your system. It is optional but recommended: it ties the line to exactly one product in the Rechnungskit catalog, even if the name or SKU changes later.

Without a productId, Rechnungskit looks up the product by SKU first and, if that is missing too, by the exact name. If you then change your SKU scheme or add a SKU later, a new catalog product appears for each variant. You notice this first where products are maintained: the same item shows up several times in the list, and each version needs its own VAT category and revenue recognition.

The ID can be any text (the primary key of your product table, for example). It only has to stay the same for each item. Different productId values mean different items, even with identical names. That keeps real variants cleanly apart.

SaaS and digital services: one endpoint

For SaaS or purely digital services, POST /v1/orders is all you need. Simply leave out the field requiresShipping (default false). Then there is no fulfillment waiting step, and /v1/fulfillments is never called.

The invoice is created as soon as the payment from the connected payment provider matches the order. Sending paymentRef speeds up the matching. There is deliberately no "paid" field: the payment status comes from the payment provider, not from the sender.

Service period (SaaS/subscriptions): the field service_period

For time-based services (SaaS, subscriptions), you send the service period in the optional field service_period. Note that this one is snake_case, not camelCase.

Rule Details
Shape object with start_date and end_date, each an ISO date YYYY-MM-DD
Complete either both keys or neither, if one is missing you get 422
Order end_date must not be before start_date

Example in the order body:

"service_period": { "start_date": "2026-06-01", "end_date": "2026-06-30" }
service_period · cases
What happens with the service period
Sent or stored on the product
Drives the deferred income (balance sheet accounting only) and appears as the service period on the ZUGFeRD invoice. A period you send takes precedence over the billing cycle on the SaaS product
Invoiceright away
Left out, no default
With EÜR nothing else happens. With balance sheet accounting, Rechnungskit holds the invoice as a task "Product without revenue recognition"
Balance sheetonly once added
Starts in an earlier financial year
With balance sheet accounting, a task "Service period in a prior year" appears, as a notice, not a block
Invoicestill right away
With EÜR, revenue counts at once, and there is no deferral.

What the period is for

The service period controls the deferred income (pRAP, passive Rechnungsabgrenzung; only for businesses that prepare a balance sheet; with EÜR, the German cash-basis accounting, revenue counts at once) and appears as the service period on the ZUGFeRD invoice. A service_period sent here takes precedence over the SaaS default on the product.

If you leave the field out, the product default applies (the billing cycle stored on the SaaS product, for example). The checkout link (/c/…) has no field for this; there the period comes from the product configuration.

Backdated service period

A start_date BEFORE the invoice date is allowed. If the start is in the same financial year, that is no problem, the annual result is correct.

If the period starts in an EARLIER financial year, usually one already closed, Rechnungskit (for balance sheet accounting) creates a task "Service period in a prior year". The months already past belong to the prior year on an accrual basis, and a correction of the balance sheet may be needed. The invoice is created anyway; the task is a notice, not a block.

Missing service period for time-based products

If you send no service_period and the product has no SaaS default (billing period) either, it depends on how you determine profit:

  • EÜR: revenue counts at once, and nothing else happens.
  • Balance sheet accounting: Rechnungskit needs the period for the deferral. The invoice is then NOT created right away but held as a task "Product without revenue recognition", which you find under Overview → Tasks. No invoice number is assigned yet.

You then set the revenue recognition on the product (Products → From your shops) or send the service_period for the order afterwards. The invoice is then created automatically.

Payment methods via the API

Payments are matched through the payment provider connections (Stripe, Mollie, PayPal, Unzer); your application supplies the order data. For pay by invoice, the field paymentGateway must match a pay-by-invoice gateway stored under Settings → Connections → Shops and payment providers exactly. Spelling counts.

If you send paymentGateway, each payment method shows up under Settings → Documents → Document rules → Payment methods and flow, where you can give it its own flow (payment received, pay by invoice or prepayment). You pick the name yourself, for example "paypal" or "vorkasse". Without the field, Rechnungskit only knows the payment method from the payment. The document rules then list it under "Detected from payments" with the fixed flow "Document when the payment arrives", because a rule needs the name on the order.

Bank transfer via Stripe (paymentGateway stripe_transfer)

If your customer is to pay by bank transfer and the money is to arrive through your Stripe account, you send the order with paymentGateway "stripe_transfer" and an email address.

stripe_transfer · flow
Bank transfer through your Stripe account
  1. Your applicationOrder with stripe_transferplus an email address
  2. RechnungskitInvoice and payment requestservices right away, goods with the shipment report
  3. Your customerTransfersto the virtual Stripe IBAN, with Stripe's reference as the payment reference
  4. StripeMatchesRechnungskit closes the open item
No Stripe invoice is created, so there is no Invoicing fee, only the fee for the transfer.

This is how it works:

  1. For a service, the invoice is created right away; for goods, only when you report shipment through /v1/fulfillments.
  2. At the same time, Rechnungskit creates a payment request for bank transfer in your Stripe account.
  3. The invoice shows your customer's virtual Stripe IBAN and, as the payment reference, Stripe's reference for exactly this payment.
  4. When the transfer arrives with this reference, Stripe matches the money and Rechnungskit closes the open item under /receivables.

Is the invoice paid?

GET /v1/invoices/{reference} and GET /v1/invoices return a payment block per document with status (open, partially_paid, paid or uncollectible), paidCents and openCents. For purchase on account and prepayment it follows the open item: it switches to paid as soon as you confirm the payment in the app under Invoices → Open items (Offene Posten) or a matched transfer arrives. An invoice for a payment at the payment provider is paid from the start. For credit notes the block is null. totals.dueCents, by contrast, is the amount printed on the invoice and never changes after issuance. So your software checks payment.status, for example to unlock access.

If a product has no revenue recognition or service type yet, POST /v1/fulfillments answers 200 with invoicesCreated: 0 and held.reason: recognition_missing. The shipment is stored, the app shows a task, and once the product is classified the invoice is created on its own. If VAT cannot be determined for another reason, the reason is held.reason: tax_blocked, held.message names it, and the order waits as a task in the app. Sending the fulfillment again triggers the invoice again but never creates a second one.

Since no Stripe invoice is created, there is no Invoicing fee, only the fee for the transfer. The transfer amount is the order's gross total, and the invoice matches it to the cent.

For this, the Stripe key needs the permissions Customers (write) and Payment Intents (write). If one is missing, no invoice is created. Instead you get an urgent task plus an email, and once you add the permission, Rechnungskit creates the invoice automatically. If the payment request is canceled in Stripe before it is paid, a cancellation invoice follows.

Invoice first, debit after (paymentGateway stripe_debit)

If the invoice should exist before the debit and your application triggers the payment through Stripe itself, send the order with paymentGateway "stripe_debit". This works for both card and SEPA direct debit.

  1. POST /v1/orders with paymentGateway "stripe_debit" and grossTotalCents. For a service, the invoice is created right away; for goods, with the fulfillment report via /v1/fulfillments.
  2. The invoice says the amount will be collected automatically from the payment method on file and asks the customer not to make a bank transfer. Your IBAN isn't on it and isn't required for this. The open item stays open until payment, and payment.status is open.
  3. You trigger the PaymentIntent yourself and link it: put the order number in the metadata (metadata.orderNo) or send the PaymentIntent ID as paymentRef. You can also do that later by sending the order again.
  4. When Stripe reports the payment as successful, Rechnungskit closes the open item. No second invoice is created, and Rechnungskit sends no payment reminders.

If grossTotalCents doesn't match the line items, you get a task instead of an invoice. A refund in Stripe creates the cancellation invoice. A returned debit reopens the item and raises a task, with no cancellation. A new debit with the same order number then closes it.

Rechnungskit needs no extra Stripe permissions for this, since your application creates the payment.

Referral credit on the order: creditRedemptions

If your customer used referral credit for an order, you send the amount in the optional field creditRedemptions. It is a list of objects:

Field Content
type "referral_credit"
amountCents whole cents, greater than 0
externalRef optional, the ID of the redemption in your system
"creditRedemptions": [{ "type": "referral_credit", "amountCents": 1000, "externalRef": "tx_81" }]

With this field, grossTotalCents is required, and the sum of the redemptions must not exceed the gross amount. Otherwise the API responds with 422.

Credit is a payment, not a discount

The invoice shows the VAT on the full amount, and the credit part counts as already paid. The payment method names both parts, such as "PayPal (37,00 €) und Empfehlungsguthaben (12,00 €)" on a German invoice. Your payment provider only collects the rest. Discounts still belong in discountNetCents.

If the order is paid entirely with credit, there is no payment at the provider. You then send financialStatus "paid", and the sum of the redemptions equals grossTotalCents. Rechnungskit then issues the invoice without an incoming payment; for goods, only when shipment is reported.

Your shop keeps the credit itself. Rechnungskit mirrors it in the credit ledger under Orders → Vouchers for the liability and the DATEV bookings, and deducts the redemption there from the customer's oldest balance. If there is no matching balance, the invoice is still correct, and a task "Referral credit without a balance" appears under Overview → Tasks.

Credit via push: credit-transactions

If your application manages credit itself, referral rewards for example, you report every movement to POST /v1/credit-transactions, up to 500 per call: { "transactions": [ ... ] }.

Field Required Content
id yes your unique identifier
type yes earn, redeem, reverse, payout or expire
email yes the customer's email address
amount_cents yes amount in cents
occurred_at yes time of the movement
delta_cents for reverse change in cents
order_ref, reverses_id, payout_ref no references to the order, the reversed movement and the payout
hc_booking_date no the date on which your accounting has booked the transaction so far

Repeating a call creates nothing twice. The response lists new (accepted) and already known (duplicates) transactions.

Once a day you report the balances to PUT /v1/credit-balances:

{ "balances": [{ "email": "...", "balance_cents": 1250 }] }

Rechnungskit compares them with the history. If a customer differs, a task is created, so a lost report gets noticed. Both endpoints need the scope orders:write. Bookings only start from the cut-over date you set under Orders → Vouchers. The guide is in Guthaben aus dem eigenen Shop übernehmen.

Letting Rechnungskit read the credit history (pull)

Instead of pushing, your shop can provide the history, and Rechnungskit reads it itself. For this, your shop provides two read-only endpoints, protected with a token:

Endpoint in your shop Returns
GET <adresse>/referral-transactions?since=<cursor>&limit=<n> { "items": [...], "next_cursor": "...", "has_more": true }
GET <adresse>/referral-balances?as_of=<YYYY-MM-DD> the balance per customer as [{ "email": "...", "balance_cents": 1250 }]

Each history entry has id, type (earn, redeem, reverse, payout or expire), email, amount_cents, occurred_at and optionally delta_cents (signed), order_ref, reverses_id, payout_ref and hc_booking_date. Entries never change; a correction is a new entry.

Setting up and poking

You enter the address, token and cut-over date under Orders → Vouchers in the section "Credit from your own shop". The step-by-step guide with dry run and cut-over date is in Guthaben aus dem eigenen Shop übernehmen.

Rechnungskit reads hourly from where it last stopped and then compares per customer: the balance in the shop against the sum of the history. If a customer differs, you see them there in a list.

A poke makes it faster: POST /api/v1/referral-credits/poke with your API key and no body. Rechnungskit then reads right away. If a poke gets lost, the next hourly run still reads everything.

Dry run and cut-over date

Without a cut-over date, this is a dry run: Rechnungskit reads and compares but books nothing. From the cut-over date, Rechnungskit takes the history into the credit ledger. On the cut-over date it creates an opening balance per customer from the history so far, without a booking, because until then your shop did its own bookings.

After that, Rechnungskit books through the account roles under Settings → Accounting → DATEV settings:

Movement Booking
Earned credit expense to liability
Reversal the other way round
Payout to the bank
Expiry as income
Refund to credit debtor account (Debitor) to liability

Rechnungskit books a redemption through the invoice (field creditRedemptions), not through the history. Credit that was created before the cut-over date and only became available after it is not booked a second time if hc_booking_date is before the cut-over date.

From the cut-over date, the comparison checks the balance in the shop against the credit ledger. Redemptions whose invoice is still missing are left out of the calculation. If something differs, a task is created. If an account role is missing, it shows up in the DATEV export as a missing mapping.

Public sector buyers: leitweg_id

Besides vat_id, the billing address (billingAddress) also accepts leitweg_id (the Leitweg-ID, the routing ID German public authorities use for e-invoices). If a valid Leitweg-ID is set, the invoice for this order is created as XRechnung 3.0, otherwise as ZUGFeRD. The API answers a formally invalid Leitweg-ID with 422.

You need a phone number in the invoice contact under Settings → Company → Company details. Without it, Rechnungskit holds the XRechnung as a task.

Testing

Use your normal API key in test mode. It is the same pipeline, EN 16931 validation and PDF creation included, but with:

  • a test number range (TEST-...),
  • no billing and no sending,
  • no effect on DATEV, OSS and ZM (EC sales list).

Fair use applies, so please no load tests. More in Test mode (sandbox).

Reporting canceled orders

If your shop cancels an order, you report it through POST /v1/orders/{orderNo}/cancel, optionally with reason and cancelledAt. What happens then depends on the state of the order.

Cancellation · responses
What a cancellation does, depending on the state
No document yet
Fully refunded: payment and refund are filed as "canceled + refunded", without a task. If you still have the money, a task is created until the refund arrives
Resultnever a document
Document already exists
Nothing changes. You report the correction through POST /v1/orders/{orderNo}/refunds or, if a payment provider took the money, by refunding there
Response409 order_invoiced
Order unknown
Never submitted? Then POST /v1/orders with status "cancelled" and paymentRef
Response404 order_not_found
You may repeat both calls as often as you like.
State of the order What happens
no document yet The order is canceled and never gets a document.
no document, payment fully refunded Rechnungskit files payment and refund as "canceled + refunded". Since there was never any revenue, there is neither a document nor a task.
no document, you still have the money A task is created, and a later refund files the case by itself.
document already exists The endpoint answers with 409 order_invoiced and changes nothing. For Kauf auf Rechnung (pay by invoice) and prepayment, report the correction through POST /v1/orders/{orderNo}/refunds. If a payment provider took the money, refund there and the cancellation invoice follows automatically.
order unknown The cancel call answers with 404 order_not_found.

For an order that was canceled before the payment was completed and therefore never submitted, you send POST /v1/orders with "status": "cancelled" and the paymentRef. Through it, Rechnungskit finds the payment along with the automatic refund and files both. You may repeat both calls as often as you like.

Reporting refunds and price reductions (refunds)

With Kauf auf Rechnung (pay by invoice) and prepayment by bank transfer, no payment provider will ever report a refund. Your system is the source. If a return, a price reduction or a full take-back happens after the invoice, report it through POST /v1/orders/{orderNo}/refunds (scope orders:write). Rechnungskit turns it into a cancellation invoice (Stornorechnung), the same way it handles refunds from shops and payment providers.

{
  "refundId": "BV-1042-R1",
  "reason": "Rücksendung 1 Flasche Spätburgunder (Korkfehler)",
  "items": [{ "productId": "spaetburgunder-2022", "quantity": 1 }],
  "refundedAt": "2026-11-10"
}
Field Meaning
refundId Required. Your own ID for the refund, unique per project. Sending the same call again returns 200 with replayed: true and the same documents. The same refundId with different content gets 409 refund_id_conflict.
reason Required, 20 to 500 characters. Printed on the cancellation invoice as the reason, like the reason in the app's cancellation dialog.
amountGrossCents Gross refund in cents. On its own, it is spread proportionally over the invoice lines.
items Item by item: each entry names exactly one reference (line = position on the invoice, starting at 1, productId from your order push, sku or name) plus quantity. Without an amount, the refund is worth exactly these items as invoiced. If you send an amount as well, it may cover at most the items plus the full shipping.
refundedAt Date of the refund, default today. It becomes the date of the cancellation invoice. It can't be in the future or before the invoice date.
alreadyPaidBack Only for invoices that are already paid: has the money gone back yet? The answer is printed on the cancellation invoice.
invoiceNumber Only needed if the order has more than one invoice.

The response (201) contains both documents with number, link and PDF, in the same fields as invoices[] in GET /v1/orders/{orderNo}: original and correction, plus remainingGrossCents (what can still be corrected) and openItem (the open item afterwards). There is no separate webhook for cancellation invoices: the response already has both documents, and GET /v1/orders/{orderNo} lists them too. The cancellation invoice is not emailed to your customer automatically. Pass the PDF link on yourself.

refunds · effect
What a reported refund does
Invoice still open
The open item drops by the refund. Refund everything and it closes as "canceled". If earlier partial payments cover the rest, it turns "paid" and invoice.paid goes out
Customer paysonly the rest
Invoice already paid
The open item stays paid and the refund is noted. You transfer the money back yourself; alreadyPaidBack records whether that has happened
You transferthe money back
Paid through a payment provider
Refund there. That refund creates the cancellation invoice automatically, and reporting it here as well would correct the invoice twice
Response409 refund_via_provider
The original invoice never changes. The cancellation invoice shows up in the DATEV export like any other cancellation.
Response Meaning
404 order_not_found No API order with this orderNo.
404 invoice_not_found invoiceNumber doesn't belong to this order.
409 order_not_invoiced No invoice yet. Use POST /v1/orders/{orderNo}/cancel.
409 invoice_not_archived The invoice is still being generated. Try again shortly.
409 invoice_ambiguous Several invoices; name one in invoiceNumber.
409 refund_via_provider Paid through a payment provider (or paymentGateway stripe_transfer/stripe_debit). Refund there.
409 refund_id_conflict The refundId was already used with different content.
409 already_fully_corrected The invoice is already canceled in full.
422 amount_exceeds_remaining More than is left to correct (details.remainingGrossCents).
422 item_not_found / item_quantity_exceeds The item isn't on the invoice, or more pieces than invoiced and not yet refunded.
422 items_amount_mismatch The amount doesn't fit the items.

In test mode you get the same documents with TEST-S- numbers. A customer who simply doesn't pay is not a refund: your tax advisor writes that receivable off as uncollectible (§ 17 Abs. 2 Nr. 1 UStG). Don't report it through this endpoint.

Why a cancellation invoice and not a "Gutschrift"

  • In German VAT law, "Gutschrift" only means an invoice the customer issues themselves (self-billing, § 14 Abs. 2 Satz 5 UStG, with the mandatory word "Gutschrift" under § 14 Abs. 4 Satz 1 Nr. 10 UStG). Cancelling or correcting your own invoice is not a Gutschrift (section 14.3 Abs. 2 Satz 5 UStAE). That's why Rechnungskit calls the document a Stornorechnung (cancellation invoice).
  • The cancellation invoice refers to the original by number and date, as § 31 Abs. 5 Satz 2 UStDV requires for a correction. It gets its own number, and the original invoice stays unchanged in the archive.
  • Correcting an e-invoice also has to be done as an e-invoice (section 14.11 Abs. 1 Satz 7 UStAE, added by the BMF letter of 15.10.2025, III C 2 - S 7287-a/00019/007/243). So the cancellation invoice is created as ZUGFeRD, like the invoice (type code 381).
  • VAT is corrected for the period in which the consideration changes (§ 17 Abs. 1 Satz 8 UStG). For money already paid, the actual repayment is what counts (section 17.1 Abs. 2 Satz 3 UStAE). So for paid invoices, send the day you transferred the money back as refundedAt.

API FAQ

Can the invoice show the billing month, e.g. "Oktober 2026"?

Yes, through service_period on the order (see Service period). The invoice shows the period as a date range, not as a month name: { "start_date": "2026-10-01", "end_date": "2026-10-31" } becomes "Leistungszeitraum: 01.10.2026 – 31.10.2026" in the invoice header on a German invoice, and the invoicing period (BG-14) in the ZUGFeRD XML. With a period, the invoice is created right away, without waiting for a shipment report. If you also want the words "Oktober 2026" on the invoice, put them in the item name, e.g. "name": "Weinabo Oktober 2026".

How do I cancel or correct an invoice through the API?

It depends on the state:

  • No invoice yet: POST /v1/orders/{orderNo}/cancel. The order never gets a document.
  • Invoice exists, Kauf auf Rechnung or prepayment: POST /v1/orders/{orderNo}/refunds, in full, for part of the amount or item by item (see Reporting refunds). You get a cancellation invoice with its own number.
  • Invoice exists, paid through a payment provider: refund at the payment provider. The cancellation invoice follows automatically.

Rechnungskit never changes or deletes an issued invoice. Corrections always come as a new document. If only the address of the same customer is wrong, use "Rechnungsanschrift korrigieren" on the invoice page in the app (see Document archive); there is no API endpoint for that.

Is there a test mode with no real invoice and no email?

Yes, a project in test mode. Your API key works there just like in live mode, with the same pipeline, validation and PDF, but with TEST numbers (TEST-…, cancellations TEST-S-…). Test documents are never emailed, aren't billed and don't flow into DATEV, OSS or ZM. Other customer emails, such as payment reminders, come to you with "[TEST]" in the subject, so you can see what would go out in live mode. Webhooks carry "test": true. Details in Testing and Test mode (sandbox).

Does Rechnungskit tell me when an invoice is paid?

Yes, in two ways:

  • Webhook invoice.paid: sent as soon as the open item of an invoice with Kauf auf Rechnung or prepayment is fully paid, exactly once per invoice and endpoint. You set it up under Settings → Connections → API with the checkout webhooks; it covers API orders too. Payload and triggers are in Invoice paid (invoice.paid).
  • Polling: GET /v1/invoices and GET /v1/invoices/{reference} return the payment block with status (open, partially_paid, paid, uncollectible), paidCents and openCents (see Is the invoice paid?).

An invoice counts as paid when you confirm the payment under Invoices → Open items, a matched bank transfer covers the amount, your shop reports the order as paid, or credit covers the rest.

Delivery contract (required for integrators)

Your system must retry failed pushes. In practice:

  1. Every 5xx or network error is transient. Deployments also cause short 502 windows.
  2. Retry with exponential backoff over at least 24 hours.
  3. Also recommended: a daily reconciliation job that resends everything your system has marked as failed.

Retries are always safe: orders are idempotent through orderNo, and the Idempotency-Key header deduplicates parallel deliveries.

A typical failure without retries: the payment arrives (the payment provider retries automatically), but the order push fails on a single 502. The payment then sits as "No order" in review until the order is sent later.

Limits, stated plainly

  • Error responses use the usual codes (400/401/403/404/409/422/429/503), with Retry-After for 429/503. Build in backoff.
  • Requests can be traced by request ID for 30 days in the API activity.

Where to find it in the app

Recent changes

Still have a question? Ask Kit in the app or write to support@rechnungskit.de
No tax or legal advice

Rechnungskit is not a tax advisory or law firm. This article explains general principles and does not replace advice from a tax advisor (Steuerberater, § 5 StBerG) or a lawyer (§ 3 RDG). Rechnungskit is built for businesses based in Germany and prepares documents, tax rates and bookings automatically. How your specific case is treated remains your decision, ideally together with your tax advisor or a lawyer.

de en