Billing

​

How you are billed

• AllRide bills you in arrears, once a month, per billable redemption. There is no deposit, no advance payment and no subscription fee.
• A billable redemption is a completed redemption of yours, whatever the channel (API, dashboard or Redemption Link). Imported legacy redemptions are not billed.
• The service month of a redemption is the calendar month of its redeemedAt in Berlin time (Europe/Berlin), whatever your partner time zone. Billing months follow Berlin time, so your analytics in another time zone can differ from the invoice at the month edges.
• On the 1st of each month at 06:00 Berlin time AllRide drafts the invoice for the previous month. AllRide reviews every draft before it is issued, so the invoice arrives a little later.
• Voided redemptions are not billed. Void before the month is invoiced and the redemption never appears on an invoice. An issued invoice is never changed afterwards, so a void after invoicing does not reduce it; if an invoice is wrong, talk to AllRide (see Corrections: Stornorechnung).
• A month with usage always produces an invoice, even if its total is zero (for example when every provider you used is free); such an invoice is immediately paid. A month without usage produces no invoice.
• The price per redemption is set by AllRide for you, possibly per provider or voucher set, and you accept it before you can redeem: see Prices and price acceptance.
• AllRide decides how you pay: by SEPA Direct Debit (the default; you set up the mandate yourself, see SEPA Direct Debit mandate) or by bank transfer against each invoice. You see the choice as preferredPaymentMethodType on your billing account.

​

Billing account and contacts

• Read it with GET /consumer/v1/billing/account (Get the billing account).
• Change it with PATCH /consumer/v1/billing/account (Update the billing account), a JSON merge patch. You can change legalName, address, vatId (null clears it), buyerReference (your Leitweg-ID for XRechnung), purchaseOrderReference (printed as your PO number), invoiceLanguage (de or en) and eInvoiceFormat.
• AllRide chooses how you pay. preferredPaymentMethodType is sepa-debit (SEPA Direct Debit, the default) or bank-transfer (you pay each invoice by bank transfer). It is set by AllRide and read-only for you; talk to your AllRide account manager if you would like to switch.

• Fields that only AllRide sets, such as mode, paymentTermsDays, voidedRedemptionsBillable and preferredPaymentMethodType, are refused with data-failed-validation and the constraint admin-only-field.
• The first two letters of vatId must match the country of your address (Greece: EL), else the constraint is vat-id-country-mismatch.
• AllRide checks EU VAT IDs against VIES. Changing vatId or the address country resets vatIdStatus to unverified until the new check completes.
• missingItems lists what blocks invoicing: legal-name, address, invoice-contact, vat-id (for EU customers outside Germany a valid VAT ID is required) and buyer-reference (required for XRechnung). Your account is active when the list is empty and incomplete otherwise; it switches back and forth automatically. An incomplete account still records usage, but AllRide cannot issue its invoice until you complete it.

​

SEPA Direct Debit mandate

1. A member with manage-consumer-billing starts the setup. The request has no body. The response holds the new payment method (setup-pending), the Stripe clientSecret (shown once), Stripe’s publishableKey and the creditor (AllRide’s name and SEPA creditor ID).
2. The dashboard loads Stripe.js with publishableKey and shows Stripe’s IBAN field together with the account holder’s name and email and the SEPA mandate text naming the creditor. The IBAN goes straight to Stripe: AllRide never receives the full IBAN and stores only the last four digits (ibanLast4), the bank code and the bank country.
3. You accept the mandate, and the dashboard confirms it with Stripe:

const stripe = await loadStripe(setup.publishableKey);
const iban = stripe.elements().create("iban", { supportedCountries: ["SEPA"] });
iban.mount("#iban");
// after the user accepted the mandate text
await stripe.confirmSepaDebitSetup(setup.clientSecret, {
  payment_method: {
    sepa_debit: iban,
    billing_details: { name: "Example Transit GmbH", email: "[email protected]" },
  },
});

4. The payment method stays setup-pending until Stripe confirms the mandate, usually within a minute, then it is active and becomes your default. The dashboard polls Get a payment method until then. A setup that is not confirmed within 24 hours (setupExpiresAt) ends setup-failed; remove it or start a new one.

• Starting it removes any other unfinished setup and cancels its SetupIntent.
• Your current mandate keeps collecting until Stripe confirms the new one. Then the new mandate is active and the default, and the old one is removed with deactivatedReasonClass: replaced. Scheduled debits move to the new mandate, with a new pre-notification. The webhook payment-method-deactivated reports the old one with reasonClass: replaced, and the activation email names the IBAN it replaced.
• If the new setup fails, your current mandate stays.

• Soft failures (for example insufficient funds) are retried twice, 7 and 14 days after the failure is reported, within 30 days of the first failure. Each retry comes with a new pre-notification.
• Hard failures (mandate revoked, account closed, account details wrong) deactivate the mandate (payment-method-deactivated) and move the invoice to bank transfer; your contacts receive the bank-transfer instructions. Set up a new mandate to return to direct debit.

​

Invoices and Stornorechnungen

• You see only issued documents. Drafts in review are invisible (404 invoice-not-found).
• Numbers are gapless per year in one series, for example VP-R-2026-000042. Stornorechnungen use the same series.
• kind tells you what an invoice is: periodic (the monthly invoice), final (after offboarding), corrective (a corrected invoice issued after a cancellation) or cancellation (a Stornorechnung, see below).
• Invoice statuses: finalised (issued, email not yet sent), sent, partially-paid, paid, overdue, uncollectible and void (cancelled by a Stornorechnung).
• Each invoice line shows the provider, voucher set, quantity, unitPrice and net amount. Amounts are Money in cents; tax rates are decimal strings such as "19.00".

​

Corrections: Stornorechnung

1. The Stornorechnung is an invoice of its own with kind: cancellation, a new number in the same series and cancelsInvoiceId pointing to the cancelled invoice. Its document refers to the original invoice number and date.
2. It mirrors the original lines with negative amounts: each line has a negative quantity and netAmount with the original, positive unitPrice; netAmount, taxAmount, grossAmount and the tax breakdown are negative. Nothing is due on it: amountDue is 0, paymentInstructions.type is settled and it stays finalised or sent.
3. The original invoice becomes void, with cancelledByInvoiceId naming the Stornorechnung and amountCancelled equal to its gross amount. Open SEPA debits or bank transfer requests for it are cancelled, and anything you already paid on it moves to your credit balance, which AllRide applies to your next invoices.
4. Where you should be billed again, AllRide issues a corrected invoice (kind: corrective) that you pay as usual.

{
  "data": {
    "resource": "document-download",
    "format": "xml",
    "url": "https://storage.googleapis.com/allride-voucher-billing/VP-R-2026-000042.xml?X-Goog-Signature=example",
    "expiresAt": "2026-11-02T08:20:00Z",
    "sha256": "9f2c1b7e4d3a5c6b8e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
    "sizeBytes": 48211,
    "fileName": "VP-R-2026-000042.xml"
  }
}

​

Fetching invoices into your ERP with an API key

1. Create an API key with the scope view-consumer-billing in the developer dashboard.
2. Subscribe a webhook endpoint to invoice-finalised, which is sent once the document exists (for Stornorechnungen too), and to invoice-voided to mark cancelled invoices.
3. On each webhook, request the document (format=xml for machine processing), download it and verify the hash:

INVOICE_ID=19017
DOWNLOAD=$(curl -s "$VOUCHER_API_BASE_URL/consumer/v1/billing/invoices/$INVOICE_ID/document?format=xml" \
  -H "Authorization: Bearer $VOUCHER_API_KEY")
DOCUMENT_URL=$(echo "$DOWNLOAD" | jq -r '.data.url')
EXPECTED_SHA256=$(echo "$DOWNLOAD" | jq -r '.data.sha256')
curl -s -o invoice.xml "$DOCUMENT_URL"
echo "$EXPECTED_SHA256  invoice.xml" | shasum -a 256 -c -

4. As a fallback for missed webhooks, poll daily for invoices issued since your last run:

curl -G "$VOUCHER_API_BASE_URL/consumer/v1/billing/invoices" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  --data-urlencode "filter[issueDate][gte]=2026-11-01" \
  --data-urlencode "sort=issueDate"

​

E-invoices (ZUGFeRD/XRechnung)

​

Usage and pricing

• Until the month is invoiced the response is an estimate (isEstimate: true), updated within about 2 minutes of each redemption. Once invoiced, invoiced: true and the amounts come from the invoice.
• priced: false means the price is still to be confirmed; such lines have no amounts.
• unitPrice is a UnitPrice: {value, scale: 4, label} with value in ten-thousandths of a euro, so 1000 is €0.10 and 1250 is €0.1250. Totals are Money in cents.
• Unit prices are set by AllRide for you and may differ per provider and voucher set; a price of zero is possible. You see only the resolved price that applies to you, never how it was derived. The Price Terms per voucher set and your acceptance of them are in Prices and price acceptance.

​

Payments and dunning

​

Billing webhooks

​

Permissions

​

Related

• Prices and price acceptance
• Analytics
• Pagination, filtering and sorting
• Webhooks
• Error catalog