Deutschlandticket 
This article explains how you can order and maintain a Deutschlandticket subscription and how you can add the German postal code (Postleitzahl).
Prerequisites
The Deutschlandticket, or also known as 49€-Ticket, is a monthly subscription ticket for puplic transit in Germany, which enables you to use all local public transport. It is valid for whole of Germany and costs 49€ per month.
Validity: on all local and regional buses, trams, metros, S-Bahn trains, and local and regional trains (RB/RE) across whole Germany, except on some RE trains operated by DB Fernverkehr.
The ticket is a monthly subscription and is valid from the first until the last day of one calendar month.
How it works
1. Product
There are two different Deutschlandticket products in the Mobilitybox API. The regular one, and the Jobticket, which is intended for employees and is 5% cheaper than the regular one.
To get the Deutschlandticket Jobticket please contact us.
Deutschlandticket product id:
"mobilitybox-product-cbe3ec49-b9ad-42f8-b694-8a41e3b8e9f8"
Product response
[
{
"id": "mobilitybox-product-cbe3ec49-b9ad-42f8-b694-8a41e3b8e9f8",
"recommended_successor_is": null,
"recommended_successor_of": null,
"local_ticket_name": "Deutschlandticket",
"local_validity_description": "Das Deutschlandticket ist ein von der Bundesrepublik Deutschland und den Bundesländern gefördertes deutschlandweit gültiges Tarifangebot im Schienenpersonennahverkehr (SPNV) und im öffentlichen Personennahverkehr (ÖPNV). Ausgenommen sind der Fernverkehr und Fahrten in der ersten Klasse. Es gilt als Monatskarte im Abo, ab dem 01.05.2023, vorbehaltlich des abgeschlossenen Gesetzgebungsverfahrens.",
"ticket_type": "month",
"customer_type": "adult",
"duration_definition": "calendar_month",
"duration_in_minutes": null,
"validity_in_minutes": null,
"price_in_cents": 4900,
"currency": "EUR",
"sold_from": "2023-04-24T22:00:00Z",
"sold_until": null,
"area_id": "mobilitybox-area-44803b80-97ca-4bb0-a215-564e4663a33b",
"identification_medium_schema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"photo_id_lite"
],
"properties": {
"photo_id_lite": {
"$ref": "#/definitions/photo_id_lite"
}
},
"additionalProperties": false
}
],
"$schema": "http://json-schema.org/draft-04/schema#",
"definitions": {
"photo_id_lite": {
"type": "object",
"title": "Photo-Id",
"required": [
"first_name",
"last_name",
"birth_date"
],
"properties": {
"last_name": {
"type": "string",
"title": "Last Name",
"examples": [
"Mustermann"
]
},
"birth_date": {
"type": "string",
"title": "Birth Date",
"format": "date",
"examples": [
"1990-01-01"
]
},
"first_name": {
"type": "string",
"title": "First Name",
"examples": [
"Max"
]
}
}
}
}
},
"tariff_settings_schema": null,
"is_subscription": true
}
]
2. Order
First step to create a Deutschlandticket is to order the product with an valid API-Key. You can add an optional order reference, where you can pass the booking reference or an user id for example.
Checkout the Order API Documentation for a detailed description of the endpoint.
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/orders.json" \
-H 'Authorization: Bearer {YOUR_API_KEY}' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"product_ids": [
"mobilitybox-product-cbe3ec49-b9ad-42f8-b694-8a41e3b8e9f8"
],
"optional_order_reference": "foobar"
}'
3. Activation
Second step to get the Deutschlandticket is to activate the coupon which is created and returned by the order request.
You have to pass an identification_medium which conforms to the identification_medium_schema of the product.
Optionally you can pass a activation_start_datetime to define in which month the first ticket should be valid. By default, the ticket is valid in the month of activation.
Checkout the Activation API Documentation for a detailed description of the endpoint.
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/coupons/mobilitybox-coupon-uuid/activate.json" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"identification_medium": {
"photo_id_lite": {
"first_name": "Max"
"last_name": "Mustermann",
"birth_date": "1990-01-01"
}
},
"activation_start_datetime": "2023-11-01T00:00:00Z",
}'
4. Retrieve Ticket
The third and last step to receive a Deutschlandticket is to fetch the ticket data with ticket_id of the coupon activate response
curl -X "PATCH" "https://api.themobilitybox.com/v5/ticketing/tickets/mobilitybox-ticket-uuid.json"
To display the Ticket in you Application check out the App Integration Documentation
5. Reorder
The Deutschlandticket is a subscription, what means that after each month there is the option to reorder the subscription to create a new ticket for the regarding month.
Optionally you can pass the subscription_cycle_id to define the month (cycle) which has to be ordered. By default the next unordered will be ordered if no subscription_cycle_id was passed.
Checkout the Reorder API Documentation for a detailed description of the endpoint.
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/subscriptions/mobilitybox-subscription-uuid/reorder.json" \
-H 'Authorization: Bearer {YOUR_API_KEY}' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"subscription_cycle_id": "mobilitybox-cycle-uuid"
}'
6. Reactivate
When a new subscription cycle was reordered how described in the point before, you can receive a new ticket_id when you call the Activation API Endpoint and passing the coupon_reactivation_key found in the previous ticket response as reactivation_key.
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/coupons/mobilitybox-coupon-uuid/activate.json" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"reactivation_key": "..."
}'
How to cancel Subscription
You can cancel the Deutschlandticket by the 10th of a month to the end of the calendar month.
To cancel a subscription you have to call the Subscription Cancel API endpoint:
curl -X "DELETE" "https://api.themobilitybox.com/v5/ticketing/subscriptions/mobilitybox-subscription-uuid.json" \
-H 'Authorization: Bearer {YOUR_API_KEY}' \
Postal Code (Postleitzahl)
It is specified that for each Deutschlandticket the postal code (Postleitzahl) for the place of residence from the passenger has to be collected.
The postal code is part of the tariff_settings which can be set for a coupon. There are two ways how to pass the German postal code via the API.
It is only necessary to pass German postal codes. If the user has an foreign postal code, you have to pass "not-germany".
Option 1: pass it via the activation request:
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/coupons/mobilitybox-coupon-uuid/activate.json" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"identification_medium": {
"photo_id_lite": {
"first_name": "Max"
"last_name": "Mustermann",
"birth_date": "1990-01-01"
}
},
"tariff_settings": {
"german_postal_code": "12345"
}
}'
Option 2: pass it via the designated add tariff settings endpoint
curl -X "POST" "https://api.themobilitybox.com/v5/ticketing/coupons/mobilitybox-coupon-uuid/tariff_settings.json" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"tariff_settings": {
"german_postal_code": "12345"
}
}'