Before you start
This playbook is for operators and e-mobility providers who invoice their customers from their own systems. That’s the case on the Invoice Data Service and No service billing service levels. On Full Service, Spirii invoices your customers for you, so your ERP receives Spirii’s invoices rather than building its own. See Billing service levels. Spirii doesn’t expose finished billing documents through the API. You build invoice lines from raw CDRs, which carry the energy, price, VAT rate, and references each line needs. You’ll need an API key and a working understanding of sessions and CDRs. Who carries the VAT on a session depends on who is the merchant; see Who is the merchant.How the pieces fit
Each CDR becomes one line. Three references on it place that line in your ERP:- The customer, to know whom to invoice. The CDR carries Spirii’s customer ID, which you map to your ERP’s customer number through the customer’s
externalId. - The charge key’s billing reference, such as a driver’s cost centre. It travels on the CDR as
auth.idTag.billingReference. - The location’s billing reference, such as a site or project code. It isn’t on the CDR: fetch it from the location, using the CDR’s
location.id.
Choose the mode for what you invoice
If you do both, run the two as separate pulls and keep the lines apart in your ERP.
Set up invoicing
A fleet operator with 600 issued charge keys is a typical case: each key’s billing reference holds the driver’s cost centre, and every month’s charging, at the depot and on the road, is posted to the ERP per cost centre.1
Map customers to your ERP
Set each customer’s
externalId to its customer number in your ERP, so a CDR’s customer resolves to an ERP account without a lookup table. If a CRM owns your customer records, the CRM integration playbook covers keeping externalId in step.2
Set billing references
Write the references your invoices need onto charge keys and locations. Both are free-text fields.
3
Pull the period's CDRs
Fetch CDRs by Store what you pull, and decide which timestamp assigns a session to an invoice period, such as
updatedAt, in the mode that matches what you invoice. To invoice one customer, add a filter on its customer ID.endedAt. Apply that choice everywhere so a session never lands in two periods.4
Keep the sessions you invoice
Keep CDRs whose
paymentMethod is Invoice. Sessions paid another way, in an app, at a payment terminal, or through a roaming partner, have already been paid for, and invoicing them again would charge twice.The filter parameter doesn’t accept paymentMethod, so apply this rule after you’ve pulled the records. Sessions with paymentMethod Free are yours to decide on, depending on how you charge for them.5
Build the invoice lines
Group the kept CDRs by customer and
price.currency, and within that by price.vatRate. For each line, take:Use the amounts on the CDR rather than recalculating them from the tariff.
price.breakdown shows how a price was arrived at, if a customer asks.Verify
Build lines for one customer and one closed month, then export that customer’s CDRs for the same month from Charge detail records in Spirii Connect. The session count, total kWh, and net amount match your ERP’s lines once you apply the same
paymentMethod rule to the export.Handle corrected CDRs
A CDR can change after you first pull it. When a faulty session’s price is corrected, the record is recalculated and itsupdatedAt moves. Keep pulling by updatedAt after a period closes, compare against what you’ve already invoiced, and raise the difference as a credit or adjustment in your ERP rather than editing an issued invoice.
Home charging reimbursement
If employees are reimbursed for home charging through payroll, the ERP that runs payroll picks up each month’s approved expense report. See Home charging reimbursement for how reports are produced and approved. The Reimbursement API authenticates with the same API key, from its own base URL:https://api.spirii.com/reimbursement.
1
List approved reports
Filter by status, and by fleet customer if you handle more than one.
2
Post each employee's amount
Fetch the report to get its expenses, one per employee.
recipientExternalId is the externalId on the employee’s customer record, which makes it the key to your payroll system. amountInCents is the amount to pay and currency its currency.For the report as a file, download it with format=csv or format=pdf from Download expense report.Best practices
- Mind the units. The Reimbursement API returns amounts in cents and energy in watt-hours. CDRs use decimal amounts and kilowatt-hours. Convert before combining the two.
- Keep
transactionIdon every line. It traces a line back to the session behind it when a customer queries an invoice. - Store CDRs locally. A CDR request returns at most 5,000 records and the API allows 120 requests per minute. Pull incrementally and build invoices from your own copy. See Rate limits.
- Page through completely. CDRs page by cursor; follow it to the end. See Pagination.
- Split by currency. A customer charging in several countries can produce sessions in more than one currency. Invoice each currency separately rather than converting.
Next steps
CRM integration
Keep the customer records these invoices depend on in step with your CRM.
Reporting and dashboards
The retrieval patterns for storing and aggregating CDRs.