Mobilitybox Ticketing Tariff Settings General Idea

Tariff Settings were introduced with Ticketing API V4. This chapter explains how you can manage the tariff settings of a coupon with the Mobilitybox API.
Tariff Settings are used to store different tariff-bound information.

Tariff Settings Schema

When a product ticket requires some tariff settings to be created, the attribute tariff_settings_schema of the product will contain a JSON Schema describing the settings needed to be set.

Example:

{
  "tariff_settings_schema": {
    "type": "object",
    "allOf": [
      {
        "type": "object",
        "required": [
          "tariffzones"
        ],
        "properties": {
          "tariffzones": {
            "$ref": "#/definitions/tariffzones"
          }
        },
        "additionalProperties": false
      }
    ],
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
      "tariffzones": {
        "type": "array",
        "items": {
          "type": "string",
          "pattern": "^(mobilitybox-area-)?.{36}$"
        },
        "title": "VRS Tarif Zonen Preisstufe 4",
        "maxItems": 4,
        "minItems": 4,
        "uniqueItems": true
      }
    }
  }
}

A coupon will have two new attributes called tariff_settings and tariff_settings_valid.
The tariff_settings attribute will return the currently saved tariff_settings for this coupon (can be null).
The tariff_settings_valid attribute will show if the given tariff_settings pass the validation of the tariff_settings_schema of the ordered product

API Add Tariff Settings

For an additional API description, check out the Ticketing API Documentation](/ticketing/documentation/api).

You must add this information before activating a coupon with the required tariff settings. There are two ways to add tariff settings to a coupon.

Add before activation

To add tariff settings before the activation, call the POST /ticketing/coupons/{id}/tariff_settings.json endpoint.
The passed data has to be a JSON Object that passes the tariff_settings_schema validation present inside the ordered product. You can't add additional information.

You can call this API multiple times, and the saved tariff_settings for the coupon will update. It will merge the existing data with the new parameters.

It will return the updated coupon data.

// body
{
  "tariff_settings": {
    //...
  }
}

ATTENTION: you can't modify the tariff settings after a coupon was activated.

Add while activating

Additionally to the adding endpoint, there is the option to add the tariff settings while activating the coupon and add the data to the body of the POST /ticketing/coupons/{id}/activate.json endpoint.
The data given here will be merged like on the other endpoint with the existing tariff settings data saved for the coupon.

// body
{
  "identification_medium": {
    //...
  },
  "tariff_settings": {
    //...
  }
}

API Remove Tariff Settings

To remove tariff settings before the activation, you have to call the DELETE /ticketing/coupons/{id}/tariff_settings.json endpoint.
You can either pass a list of strings for which keys of the tariff settings you want to delete or pass nothing and set the complete tariff settings to null

// body
{
  "tariff_settings_keys": ["key1", "key2"]
}

ATTENTION: you can't modify the tariff settings after a coupon was activated.

Tariffzones

One tariff setting is the tariff zones list. When you want to create a multi-tariffzone ticket, you need to define which tariff zones the ticket should be valid for.

You have to add a list of Mobilitybox Area IDs (["mobilitybox-area-uuid", "mobilitybox-area-uuid2", ...]`).

ATTENTION: Current there is no Validation if the given tariff zones will create a valid ticket. The responsibility to pass a valid set of tariff zones is on your site!