Mobilitybox Ticketing Invoicing API

In order to provide your users with the best an quickest billing experience, we have developed an Invoicing API. The API allows you to fully automate the invoicing process. As there is a variety of tickets and purchasing processes, we have incorporated the relevant use-cases in the system. All of them are explained in the chapters below. If you have any questions, feel free to reach out at any time.

Prerequisites

The ticketing invoicing is based on billable items created when a product is ordered or a subscription is reordered. They describe one item that can be billed and not affected by restores.

Single Tickets

A billable item will be created for the coupon when a single ticket is ordered. The billable_item_id attribute of the coupon will be set. Example:

{
  "id": "mobilitybox-coupon-uuid",
  "billable_item_id": "mobilitybox-billable-uuid",
  //...
}

Subscriptions

When the ticket is a subscription for each subscription cycle that is ordered/reordered a billable item will be created, and the subscription cycle will have the billable_item_id set. There will be no billable item for the coupon itself, and the billable_item_id` will be null. Example:

{
  "id": "mobilitybox-coupon-uuid",
  "billable_item_id": null,
  "subscription": {
    "id": "mobilitybox-subscription-uuid",
    "subscription_cycles": [
      {
        "id": "mobilitybox-cycle-uuid1",
        "billable_item_id": "mobilitybox-billable-uuid1",
        //...
      },
      {
        "id": "mobilitybox-cycle-uuid2",
        "billable_item_id": "mobilitybox-billable-uuid2",
        //...
      }
    ],
    //...
  }
  //...
}

NOTE: The next chapters will explain the usage of some invoicing api endpoints in an abstract way. Please check out the Ticketing API documentation for a detailed api description.

Logic for "Leistungszeitraum" on the Invoice

1. If one item (specification: order time) -> "Leistungszeitpunkt: 13.01.2024 12:42Uhr"
2. If several items and all in the same month (order time) -> "Leistungszeitraum: Dezember 2023"
3. If several items and they are in different months (last and first order time) -> "Leistungszeitraum: 15.12.2023 - 14.01.2024"

Tags for Invoice Texts

To put information which is generated after creating the invoice into the texts of an invoice like the invoice number or the full amount, it is possible to use tags. Simply put {{tag_name}} into subject, custom_text_before_table or/and custom_text_after_table.

Available tags:

tag	description	example
invoice_number	basic invoice number, can be used f.e. in the "purpose of transfer"	"001-00012345"
total_amount	amount of what the customer has to pay	"49,00 €"

Example:

{
  "custom_text_after_table": "Bitte überweisen Sie die Summe von {{total_amount}} unter Verwendung des Verwendungszwecks: '{{invoice_number}}' innerhalb von 14 Tagen auf das unten aufgeführte Konto."
}

Outcome:

Bitte überweisen Sie die Summe von 49,00€ unter Verwendung des Verwendungszwecks: '001-00012345' innerhalb von 14 Tagen auf das unten aufgeführte Konto.

1. Simple Invoicing - without customer

The simplest use case is to create an invoice for a single billable item without a customer set. You can POST /v5/ticketing/billable_item/{id}/invoice.json with passing a billable item id and some additional meta information that should be placed on the invoice like a subject, notes and some texts. Example:

{
  "subject": "Rechnung",
  "notes": "some notes...",
  "custom_text_before_table": "custom text before table ...",
  "custom_text_after_table": "custom text before table ..."
}

2. Medium Invoicing - with customer

Based on the simple invoicing example from above, it is also possible to create an invoice for a specific customer. One use case is for example to simply add the name and address of the customer on the invoice.

1. create a customer

To create a customer you have to call the following endpoint: POST /v5/ticketing/customers.json You can pass an attribute called address_lines. This is a list of strings representing the name and address written on the invoice. It has to have a minimum of one and a maximum of five lines. Each line has a maximum of 35 characters. Example:

{
  "customer": {
    "address_lines": [
      "Max Mustermensch",
      "Beispielstraße 123",
      "12345 Beispielstadt"
    ]
  }
}

2. add customer to a billable item

A customer can be assigned to a billable item by calling the following endpoint: PUT /v5/ticketing/billable_item/{id}.json You have to pass the id of the customer. Example:

{
  "customer_id": "mobilitybox-customer-uuid"
}

(There are also different attributes possible to pass at that api endpoint, but they will be explained in the chapters below).

3. create the invoice

After creating a customer and adding it to a billable item, an invoice for this billable item can be created for this specific customer by calling the following endpoint: POST /v5/ticketing/billable_item/{id}/invoice/{customer_id}.json You can pass some additional meta information that should be placed on the invoice like a subject, notes and some texts.

3. Medium Invoicing - with splits on single billable items

A more complex use case is when a billable item has to be splitted to multiple customers.

1. create multiple customers

The first step is to create a customer for each person or company that is involved with the following endpoint: POST /v5/ticketing/customers.json

2. add multiple customers to a billable item

To add multiple customers to a billable item we introduce to concept of splits. A split defines which customer has to pay which amount of the billable item. To set a split of a billable item you have to call the following endpoint: PUT /v5/ticketing/billable_item/{id}.json

Note: the order of the passed split items defines which customer is the beneficiary of the ordered product. So the the first split item is the split item of the beneficiary.

Instead of passing only one customer id you pass a split which contains a list of customer ids and which amount they have to pay. Example:

// split for a billable item with an amount of 4900
{
  "split": [
    {
      "customer_id": "mobilitybox-customer-uuid1",
      "amount_in_cents": 1000
      },
    {
      "customer_id": "mobilitybox-customer-uuid2",
      "amount_in_cents": 3900
    }
  ]
}

Note: when adding a splits the sum of all amounts has to be the full amount of the billable item. Otherwise the request will through an error.

3. create the invoice

After creating the customers and adding them to a billable item, multiple invoices for this billable item can be created. You can create for each customer an invoice where the other users of the split are shown as passive participants. To do so call the following endpoint: POST /v5/ticketing/billable_item/{id}/invoice/{customer_id}.json You can pass some additional meta information that should be placed on the invoice like a subject, notes and some texts.

4. Complex Invoicing - with billable collections on single customers

This chapter explains how you can combine multiple billable items in one invoice. Therefor you can create a billable collection.

1. create a customer

To create a customer you have to call the following endpoint: POST /v5/ticketing/customers.json You can pass an attribute called address_lines. This is a list of strings representing the name and address written on the invoice. It has to have a minimum of one and a maximum of five lines. Example:

{
  "customer": {
    "address_lines": [
      "Max Mustermensch",
      "Beispielstraße 123",
      "12345 Beispielstadt"
    ]
  }
}

2. create a billable collection

The next step is to create a billable collection. It will return a billable collection id you can use in the next steps. Use the following endpoint: POST /v5/ticketing/billable_collections.json

3. add billable item to billable collection

There are two ways to add a billable item to a billable collection. The first option is to pass the billable collection id while adding a customer/split to the billable item. You can also pass only the billable collection id without the other attributes. Use the following endpoint: PUT /v5/ticketing/billable_item/{id}.json Example:

{
  "customer_id": "mobilitybox-customer-uuid",
  "billablable_collection_id": "mobilitybox-collection-uuid"
}
// or:
{
  "split": [
    //...
  ],
  "billablable_collection_id": "mobilitybox-collection-uuid"
}
// or:
{
  "billablable_collection_id": "mobilitybox-collection-uuid"
}

With the other option its possible to add multiple billable items to a billable collection at once. Therefor use the following endpoint: POST /v5/ticketing/billable_collection/{id}/billable_items.json You have to pass a list of billable item ids. Example:

{
  "billable_item_ids": [
    "mobilitybox-billable-uuid1",
    "mobilitybox-billable-uuid2",
    "mobilitybox-billable-uuid3"
  ]
}

3. create the invoice

After creating a customer and adding it to a billable item, an invoice for this billable item can be created for this specific customer. When each billable item in the collection has only one and the same customer assigned you can call the endpoint without the customer_id with the same result: POST /v5/ticketing/billable_item/{id}/invoice.json

You can pass some additional meta information that should be placed on the invoice like a subject, notes and some texts.

5. Complex Invoicing - with billable collections and splits

You can also add billable items that contain splits to a billable collection. To create an invoice that include all billable items of the collection for a specific customer you have to call the following endpoint: POST /v5/ticketing/billable_item/{id}/invoice/{customer_id}.json