Billing and VAT

TandemDrive organizes billable items, like charge sessions, into billing boxes, each representing the contents of a (future) billing document. These boxes are then grouped into review-sets, allowing users to review, approve, and invoice related boxes all at once.

When (almost) all billable items for a given period have been received, it’s time to close the corresponding review-set. Once closed, you can review each box within the set. If any box appears to have an issue, you can mark it as “deferred”, enabling you to approve the rest of the review-set while deferring specific boxes until they are ready. Based on your configuration, TandemDrive will proceed to generate billing documents and mark the approved boxes as “finalized”. Deferred boxes can be approved individually when they are ready for invoicing.

A more in-depth explanation of the individual concepts is provided in the sections below.

Positive and negative monetary amounts

Note: This section applies only to billing API endpoints. Other endpoints may interpret monetary amounts differently.

In TandemDrive, a “seller” (MSP or CPO) provides services to customers and roaming partners via the TandemDrive platform.

• Positive amounts: indicate revenue to the seller (e.g., customer charging fees).

• Negative amounts: indicate expenses from the seller (e.g., energy reimbursements or reverted charging fees).

Exception: Some billing documents generated by TandemDrive, such as purchase orders or self-billing invoices, may display negated monetary amounts. This negation only applies to these documents, while the API retains the original amounts. When this occurs, the negate_document_amounts property in the billing box is set to true.

Review-sets

Billing boxes are organized into review-sets, with all boxes in a review-set belonging to the same billing series. A review-set groups billing boxes from the same invoice period. These sets are automatically created when a new period begins (e.g., a new month, quarter, or year). Review-sets can be closed and approved via TandemDrive Console. Approval should only occur after the review-set is thoroughly reviewed, as invoicing begins immediately upon approval.

Besides closing and approving all billing boxes of one review-set in one go, it’s also possible to close and approve a single billing box via TandemDrive Console.

Billing boxes

In TandemDrive, a billing box represents the contents of a billing document, such as an invoice, debit note, or credit note. It is used to gather billable items for a specific party (a customer or a roaming partner), and is tied to a particular invoicing period.

A billing box contains one or more roll-ups, which correspond to the lines that will appear on the invoice. Each roll-up has unique properties, such as product category and VAT kind, ensuring that only similar items are grouped together.

Billable items, such as a charge session, are referred to as billing items. A billing item can have one or more sub-items, representing different cost components. For example, a charge session might include sub-items for energy costs and a one-time fee.

Items with different VAT countries are stored in separate billing boxes.

Box state

A billing box in TandemDrive typically progresses through the following states:

• Open: TandemDrive can continue adding billing items to this box. It remains open until manually closed.

• Closed: No new items will be added by TandemDrive. However, manual changes are still possible through the API or Console. The “closed” state allows the box to be reviewed before approval.

• Approved: The box has been approved, either via the API or Console. Only closed boxes can be approved. Once approved, the box is ready for generating the final billing document, such as an invoice, credit note, or debit note. Document generation can be done either by TandemDrive or an external system.

• Ready: TandemDrive is done generating documents and the box is ready for invoicing.

• Finalized: The primary billing document has been created, and the invoice code and date have been set. Only approved boxes can reach this state. If TandemDrive generates the document, it will be available for download.

Transferring boxes

Typically, you’ll want to copy the contents of a billing box into a financial system, such as an invoicing or bookkeeping system.

You can use our API to request boxes that haven’t been transferred yet. Once you’ve successfully stored the box’s content in your system, use the API to mark the box as “transferred”. This process works as a queue, with documents ready for transfer. To prevent duplication, process each box individually, ensuring no box is transferred more than once.

Only approved boxes should be transferred, as boxes that haven’t been approved are still subject to change.

The “transferred” state is distinct from the “finalized” state, as the timing of transfer may vary based on your specific use case. For example:

• If TandemDrive generates the primary billing document and you’re transferring it to a bookkeeping system that also needs to store the document, the transfer should occur after the box is finalized.

• If invoices are created outside of TandemDrive, you may want to transfer the box immediately after approval. Later, once the invoice is created, you can mark the box as finalized.

Deferred

The “deferred” state signifies that the box is not yet ready for invoicing. TandemDrive Console users have the option to manually mark boxes as “deferred.” When a box is deferred, it will not be included in the approval process of its associated review-set.

Use this state if there are issues with the box that need resolution before proceeding.

Once any issues with a deferred box have been resolved, the deferred state can be removed, allowing the box to be approved individually.

Withhold

A box may be placed in the “withhold” state to prevent TandemDrive from generating the primary billing document (e.g., the invoice PDF) upon the box’s approval. Other documents will still be generated as needed.

The “withhold” state is helpful for special agreements that require specific formats or contents for their primary billing documents, making the standard document inappropriate. Each party in TandemDrive has a “withhold billing” property, which automatically marks new billing boxes for that party as “withhold.”

When a box is marked as “withhold”, it is still possible to finalize it, using the API, by assigning an invoice code and date and submitting an externally created document.

Unlike “deferred”, which postpones invoicing, “withhold” restricts the generation of the primary billing document by TandemDrive. Once a box is approved, the “withhold” state cannot be newly applied but can still be removed, even after approval, allowing TandemDrive to proceed with generating the primary billing document.

Billing series

A billing series allows you to manage separate collections of billing boxes within the same administration. Each billing series defines its own billing properties, such as:

• Document type (e.g., invoice, debit note, credit note)
• Payment period
• Item roll-up method
• Billing document templates (such as an invoice PDF template)
• Invoice code numbering and pattern

Any administration must have at least one billing series to enable billing. The appropriate billing series is selected according to the billing series rules, which can be viewed and modified in TandemDrive Console.

The billing series rules define if a product item is billed. A billing series rule is defined by an administration, validity period, product category and optionally a series indicator and customer reimbursement VAT. For charge sessions the end timestamp of the session has to match the validity period. For recurring costs the start timestamp of the recurring period has to match the validity period.

VAT

A VAT rate defines the VAT percentage for a specific country and VAT kind. Common VAT kinds include: “standard”, “reduced”, “zero”, and “exempt”. VAT rates have validity periods, allowing for percentage changes over time.

The final VAT percentage is re-determined when a billing box is approved, as billing documents are typically sent post-approval and must use the valid percentage at that time. For instance, if the VAT percentage changes on January 1st and a billing box with many items from December is approved in January, the percentage valid in January will be used.

Determining VAT

To calculate VAT, the following steps are performed:

1. Determine the VAT country
2. Determine the VAT kind
3. Determine the VAT rate

In certain cases, this process can be overridden, such as:

• EU reverse charge applies.
• The reimbursement for a charge session is VAT exempt. In such cases, the charge session pricing may also be VAT exempt.

VAT country

Each seller within TandemDrive can set VAT policies for different countries. These policies define how VAT is handled for various foreign countries. Sellers can choose to use the VAT of the origin country (e.g., the location of a charge session) or the VAT from the seller’s local country. Using the origin VAT country generally means the seller must pay VAT in that country and likely requires a VAT number for that country.

If no policy is defined for a particular country, it can either be flagged as an error that needs resolution or default to the seller’s VAT country. This behavior is configurable for each seller.

VAT kind

Once the VAT country is determined, VAT rules are applied to identify the appropriate VAT kind. VAT rules select the appropriate VAT kind for each item, based on the product category, and optionally the VAT country or VAT indicators. These rules apply to each item’s subtotal. VAT rules have specific validity periods, allowing for changes over time.

VAT rate

Once the VAT country and VAT kind are identified, the VAT rate (percentage) is determined. VAT rates also have validity periods as they may change over time.

VAT examples

Below are examples based on the following setup:

• The MSP is based in the Netherlands.
• The MSP has the following VAT policies:
  • Belgium: Use the original VAT country.
  • Norway: Use the original VAT country.
• The MSP has a fallback VAT policy to apply VAT from the seller’s country (Netherlands).
• A rate rule for charge sessions applies the standard VAT rate, regardless of the country.
• The VAT rates for each country are as follows:
  • Netherlands “standard” VAT: 21%
  • Belgium “standard” VAT: 21%
  • Norway “standard” VAT: 25%
  • Germany “standard” VAT: 19%

Examples of charge sessions based on the location of the session:

• A session in Norway will result in the standard Norwegian VAT rate of 25%.
• A session in Belgium will result in the Belgian VAT rate of 21%.
• A session in Germany will result in the Dutch VAT rate of 21% being applied because no VAT policy for Germany was defined.

Corrections in Billing Boxes

Charge sessions appear only once within a single billing box. However, due to corrections, a single charge session might appear in multiple billing boxes.

To illustrate how corrections are handled, let’s consider a scenario with an initial billing box containing a single priced charge session:

Billing Box 1 (Open):

• Category: MSP Charge session, Count: 1, Volume: 30
  • Charge Session: A, 30.0 kWh, € 18.00

Later, this charge session (A) is repriced to € 17.00. The way this correction is applied depends on whether the original billing box has already been closed (i.e., the invoice has been generated).

Scenario 1: Invoice Not Yet Generated (Billing Box 1 is Open)

If Billing Box 1 is still open when the repricing occurs, the charge session within that box will be directly updated:

Billing Box 1 (Open):

• Category: MSP Charge session, Count: 1, Volume: 30
  • Charge Session: A, 30.0 kWh, € 17.00

Scenario 2: Invoice Already Generated (Billing Box 1 is NOT open)

If the invoice for Billing Box 1 has already been created, the correction will be handled differently. The original charge session will remain as it was in the closed box, and a reversal and the corrected charge session will be added to the next open billing box:

Billing Box 1 (Closed):

• Category: MSP Charge session, Count: 1, Volume: 30
  • Charge Session: A, 30.0 kWh, € 18.00

Billing Box 2 (Open):

• Category: MSP Charge session, reversion, Count: 1, Volume: 30
  • Billing Item: revert, revises A, € -18.00
• Category: MSP Charge session, Count: 1, Volume: 30
  • Charge Session: A, 30.0 kWh, € 17.00

In this second scenario, Billing Box 2 contains two entries related to the corrected charge session: a reversal of the original charge (€ -18.00) and the new, correctly priced charge session (€ 17.00). This ensures that the financial records are accurate while maintaining a history of the original billing. Consequently, when a correction occurs after an invoice has been generated,
the same charge session (A) will be present in both the original, closed
billing box (Billing box 1) and the subsequent open billing box (Billing box 2).