Mobilitybox Ticketing Subscriptions General Idea

This chapter explains how subscriptions work in the Mobilitybox API. This contains an explanation of 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 several subscription cycles. A subscription cycle defines a specific period for which a ticket is created. The duration_definition of the booked product defines the length of a subscription cycle.
For example, there are:

"duration_definition": "calendar_month"

This means a ticket and a subscription cycle are valid from the first to the last day of a calendar month.

The returned subscription gives you information about the current subscription, the next subscription, and the next unordered subscription cycle. (Hint: the next_subscription_cycle and next_unordered_subscription_cycle could be the same and are nullable)

The current_subscription_cycle is determined based on the following rules:
1. If there is an active subscription cycle for the current period, it will be considered as the current_subscription_cycle.
2. If only one subscription cycle is activated for a future period, the first one in chronological order will be designated as the current_subscription_cycle.
3. If only one subscription cycle exists for a past period, it will be considered as the current_subscription_cycle, with preference given to the most recent one.

Reorder a Subscription

When a subscription is created, the first subscription cycle is also created. When the coupon is activated, it will set the valid_from and valid_until times for the first cycle and generate a new one. This new cycle must be reordered to create a new ticket for the new cycle period.

Check out 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 of the coupon.
You need the coupon_reactivation_key returned in the ticket data to receive the next ticket. 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 have 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 gets canceled, you can't reactivate or reorder new subscription cycles. But ordered subscription cycles will stay ordered, and you can receive their tickets.