Mobilitybox Ticketing Subscriptions General Idea
This chapter explains how subscriptions work in the Mobilitybox API. This contains a explanation how to create a subscription and how to manage it.
Create a Subscription
A subscription is created when ordering a product which has the attribute:
"is_subscription": true
The returned coupon will have an attribute called subscription:
{
"order_id": "mobilitybox-order-uuid",
"optional_order_reference": "Optional Order Reference",
"restore_secret": "mobilitybox-restore-secret-uuid",
"coupons": [
{
"id": "mobilitybox-coupon-909233de-0039-4acf-9530-da4d04c78515",
"original_coupon_id": null,
"restored_coupon_id": null,
"product": {...},
"area": {...},
"subscription": {
"id": "mobilitybox-subscription-uuid",
"original_subscription_id": null,
"restored_subscription_id": null,
"activate": true,
"coupon_reactivatable": true,
"current_cycle_valid_from": "2023-01-31T23:00:000Z",
"current_cycle_valid_until": "2022-02-28T22:59:59Z",
"ordered_until": "2022-03-31T22:59:59Z",
"current_subscription_cycle": {
"id": "mobilitybox-cycle-uuid",
"valid_from": "2023-01-31T23:00:000Z",
"valid_until": "2022-03-31T22:59:59Z",
"ordered": false,
"coupon_activated": false
},
"next_subscription_cycle": {
"id": "mobilitybox-cycle-uuid",
"valid_from": "2023-01-31T23:00:000Z",
"valid_until": "2022-03-31T22:59:59Z",
"ordered": false,
"coupon_activated": false
},
"next_unordered_subscription_cycle": {
"id": "mobilitybox-cycle-uuid",
"valid_from": "2023-01-31T23:00:000Z",
"valid_until": "2022-03-31T22:59:59Z",
"ordered": false,
"coupon_activated": false
}
},
"activated": true,
"environment": "test"
}
]
}
A subscription contains information about its current status and consist of several subscription cycles. A subscription cycle defines a specific period for which a ticket is created. The length of a subscription cycle is defined by the duration_definition
of the booked product.
For example there is:
"duration_definition": "calendar_month"
which means that a ticket and a subscription cycle is valid from the first until the last day of a calendar month.
The returned subscription gives you information about the current and next subscription cycle and about the next unordered subscription cycle. (Hint: the next_subscription_cycle
and next_unordered_subscription_cycle
could be the same and are nullable)
Reorder a Subscription
When a subscription is created, the first subscription cycle will be created as well. After the activation of the coupon it will set the valid_from
and valid_until
times for the first cycle and creates a new cycle as well. This new cycle has to be reordered to generate a new ticket for the time period of the new cycle.
Checkout the Ticketing API Documentation for detailed information about the
/ticketing/subscriptions/{id}/reorder.json
endpoint.
Receive a Ticket for each subscription cycle
For each subscription cycle there is one ticket. The first ticket_id
will be returned after activation the coupon.
To receive the next ticket you need the coupon_reactivation_key
returned in the ticket data. With that key you can call the /ticketing/coupons/{id}/activate.json
endpoint again and receive a new ticket id for the next cycle when this was already reordered. For the next period you proceed the same. Each ticket will a new coupon_reactivation_key
for the next cycle.
Cancel a Subscription
You can cancel a subscription with the DELETE /ticketing/subscriptions/{id}.json
endpoint. After a subscription got canceled, you can't reactivate it or reorder new subscription cycles. But ordered subscription cycles will stay ordered and you can receive their tickets.