Deutschlandticket 
This article explains how to order and maintain a Deutschlandticket subscription and add the German postal code (Postleitzahl).
Prerequisites
The Deutschlandticket, or 49€-Ticket, is a monthly subscription ticket for public transit in Germany, enabling you to use all local public transport. It is valid for the 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 the whole of Germany, except on some RE trains operated by DB Fernverkehr.
The ticket is a monthly subscription valid from the first to the last day of one calendar month.
How it works
1. Product
There are two different Deutschlandticket products in the Mobilitybox API. The regular ticket and the Jobticket for employees which is 5% cheaper than the regular ticket.
To get the Deutschlandticket Jobticket, please get in touch with 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
The first step to creating a Deutschlandticket is to order the product with a valid API-Key. You can add an optional order reference, where you can pass the booking reference or a user ID for example.
Check out the Order API Documentation](/ticketing/documentation/api#/Order/createOrder) for a detailed endpoint description.
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
The second step to get the Deutschlandticket is activating the coupon created and returned by the order request.
You have to pass an identification_medium, which conforms to the identification_medium_schema of the product.
You can also specify an activation_start_datetime to determine the month in which the first ticket will be valid. By default, the ticket is only valid during the month of activation.
Check out the Activation API Documentation](/ticketing/documentation/api#/Coupon/activateCoupon) 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 your Application check out the App Integration Documentation
5. Reorder
The Deutschlandticket is a subscription, which means that after each month, there is the option to reorder the subscription to create a new ticket for the month.
Optionally, you can pass the subscription_cycle_id to define the month (cycle) which has to be ordered. The next unordered cycle will be ordered by default if no subscription_cycle_id was passed.
Check out the Reorder API Documentation](/ticketing/documentation/api#/Subscription/reorderSubscription) for a detailed endpoint description.
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 is reordered as described in the previous point, you can receive a new ticket_id when you call the Activation API Endpoint and pass 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 to pass the German postal code via the API.
It is only necessary to pass German postal codes. If the user has a foreign postal code, you must 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"
}
}'