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.