Mobilitybox

BETA: Mobilitybox Ticketing Invoicing Idea

The Invoicing API will be introduced with Ticketing API V5. This a beta version and it's likely that there will be changes accordingly to the endpoints.

This article explains how you can create invoices.
It is arragend in different chapters which explain the invoicing on different use cases with varying complexity.

Prerequisites

The ticketing invoicing is based on billable items, which are created when a product is ordered or a subscription is reordered.
They are describing one item that can be billed and its not affected of restores.

Single Tickets

When a single ticket is ordered, a billable item will be created for the coupon. 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 which is ordered/reordered a billable item will be created and the subscription cycle will have the billable_item_id set. For the coupon itself there will be no billable item 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.

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.
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

{
  "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