---
openapi: 3.0.1
info:
  title: Mobilitybox API v8
  version: v8
  description: |
    <br>
    ## The Mobilitybox v8 APIs offer information about how long a coupon is activatable after the initial order.

    Deutschlandticket Coupons will only be valid for activation ***within 72 hours after initial ordering***. After this time period without ordering they will be revoked. There is a new attribute for Coupons called `activatable_until` which shows how long a coupon is activatable after the initial order.

servers:
  - url: "https://api.themobilitybox.com/v8"

components:
  headers:
    Idempotency-Key:
      in: header
      name: Idempotency-Key
      schema:
        type: string
        minLength: 36
        maxLength: 255
      description: |
        Setting the `Idempotency-Key` header enables idempotency for this request. Sending the same request twice with the same `Idempotency-Key` leads into receiving the same result and execute the operation only once.
        For more information on requirements for the key used and expected behavior, checkout the [Idempotent Request Documentation](/dashboard/idempotent_requests).
  schemas:
    environment:
      type: string
      example: test
      enum:
        - live
        - test
    createOrderResponse:
      type: object
      properties:
        order_id:
          type: string
          example: "mobilitybox-order-3b8187d4-d739-4779-b314-e1311994809d"
        optional_order_reference:
          type: string
          example: "Optional Order Reference"
          description: This is optional the reference that has been put during the order creation process
          nullable: true
        restore_secret:
          type: string
          description: This key is used to restore coupons for lost tickets in this order. Save it because it's only returned by the order create endpoint.
          example: "mobilitybox-restore-secret-uuid"
        environment:
          "$ref": "#/components/schemas/environment"
        coupons:
          "$ref": "#/components/schemas/coupons"
    restoreOrderResponse:
      type: object
      properties:
        order_id:
          type: string
          example: "mobilitybox-order-3b8187d4-d739-4779-b314-e1311994809d"
        optional_order_reference:
          type: string
          example: "Optional Order Reference"
          description: This is optional the reference that has been put during the order creation process
          nullable: true
        environment:
          "$ref": "#/components/schemas/environment"
        coupons:
          "$ref": "#/components/schemas/restoredCoupons"
    orderResponse:
      type: object
      properties:
        order_id:
          type: string
          example: "mobilitybox-order-3b8187d4-d739-4779-b314-e1311994809d"
        optional_order_reference:
          type: string
          example: "Optional Order Reference"
          description: This is optional the reference that has been put during the order creation process
        environment:
          "$ref": "#/components/schemas/environment"
        coupons:
          "$ref": "#/components/schemas/coupons"
    coupons:
      type: array
      items:
        "$ref": "#/components/schemas/coupon"
    restoredCoupons:
      type: array
      items:
        "$ref": "#/components/schemas/coupon"
      description: New restored Coupons. (only these where the original coupon IDs were passed in the request body)
    coupon:
      type: object
      properties:
        id:
          type: string
          example: "mobilitybox-coupon-uuid-1"
        original_coupon_id:
          type: string
          description: ID of the old coupon, which was restored. For example, when you restore Coupon-A, the new coupon will have the ID of Coupon-A set in its `original_coupon_id` attribute
          example: "mobilitybox-coupon-uuid-2"
          nullable: true
        restored_coupon_id:
          type: string
          description: ID of the new coupon, which is the restored instance. For example, when you restore Coupon-B, this will have the attribute `restored_coupon_id` set to the new Coupon-B-Restored ID
          example: "mobilitybox-coupon-uuid-3"
          nullable: true
        billable_item_id:
          type: string
          description: id of the billable object. This ID will not change if the coupon is restored. It's null if the ordered product is a subscription (there, the subscription cycles are the billable items and will contain a `billable_item_id`)
          example: "mobilitybox-billable-uuid"
          nullable: true
        product:
          "$ref": "#/components/schemas/product"
        area:
           "$ref": "#/components/schemas/area"
        subscription:
            "$ref": "#/components/schemas/subscription"
        activated:
          type: boolean
          description: "shows if the coupon was activated (for subscription coupons: only for initial activation)"
          example: true
        earliest_activation_start_datetime:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        latest_activation_start_datetime:
          type: string
          format: date-time
          example: '2022-31-12T00:00:00Z'
        activatable_until:
          type: string
          format: date-time
          example: '2022-05-01T12:30:00Z'
        tariff_settings:
          type: object
          description: "shows the saved tariff settings for a coupon. Can be null."
          example: { tariffzones: ["mobilitybox-area-uuid1", "mobilitybox-area-uuid2", "mobilitybox-area-uuid3"]}
          nullable: true
        tariff_settings_valid:
          type: boolean
          description: "shows if the saved tariff_settings passes the validation of the tariff_settings_schema of the ordered product. It can be null, if the ordered product has no tariff_settings_schema"
          example: true
          nullable: true
        environment:
          "$ref": "#/components/schemas/environment"
    products:
      type: array
      items:
        "$ref": "#/components/schemas/product"
    areas:
      type: array
      items:
        "$ref": "#/components/schemas/area"
    product:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-product-1b9f706d-5e3f-46f6-908e-a82455960c47
        recommended_successor_is:
          type: string
          example: mobilitybox-product-uuid
        recommended_successor_of:
          type: string
          example: mobilitybox-product-uuid
        local_ticket_name:
          type: string
          example: 24StundenTicket 1 Pers. 1a (Handy)
        local_validity_description:
          type: string
          example: Berechtigt zu beliebig häufigen Fahrten in der Startgemeinde. Es
            ist nicht übertragbar und gültig für 24 Stunden.
        area_id:
          type: string
          example: mobilitybox-area-2b8dc1a8-0506-462f-b319-b8e6b47b424a
        ticket_type:
          type: string
          example: single
          enum:
          - single
          - day
        customer_type:
          type: string
          example: adult
          enum:
          - adult
          - child
          - both
        duration_definition:
          type: string
          example: "duration_in_minutes"
          description: describes the type of validity period of the ticket. For example, duration_in_minutes means the ticket is valid for a specific time in minutes. calendar_month means the ticket is valid for a calendar month, for example, 01.03.2023 to 31.03.2023. Flexible means the ticket is valid for a specific time, e.g., flexible_week from Tuesday to Tuesday next week.
          enum:
            - duration_in_minutes
            - calendar_year
            - calendar_month
            - calendar_weekend
            - calendar_day
            - flexible_year
            - flexible_month
            - flexible_weekend
            - flexible_week
            - flexible_day
        duration_in_minutes:
          type: integer
          example: 1440
        validity_in_minutes:
          type: integer
          example: 1440
          deprecated: true
          description: validity_in_minutes is deprecated in v3 and will be removed in v8, please checkout duration_definition and duration_in_minutes instead
        price_in_cents:
          type: integer
          example: 712
        currency:
          type: string
          example: EUR
        sold_from:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
          nullable: true
        sold_until:
          type: string
          format: date-time
          example: '2022-12-31T23:59:59Z'
          nullable: true
        earliest_activation_start_datetime:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
          nullable: true
        identification_medium_schema:
          type: object
          description: |
            This is a [JSON Schema](https://json-schema.org/) that will be used to validate the identification medium when activating a coupon (see coupon activation endpoint)
        tariff_settings_schema:
          type: object
          description: |
            This is a [JSON Schema](https://json-schema.org/) that will be used to validate the tariff settings when activating a coupon (see coupon activation endpoint)
          nullable: true
        possible_rendering_options:
          "$ref": "#/components/schemas/ticket_possible_rendering_options"
    ticket:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-ticket-bac3f6b1-20bf-41b6-8bdc-5068d56364ad
        coupon_id:
          type: string
          example: mobilitybox-coupon-uuid
        coupon_reactivation_key:
          type: string
          example: key
        product:
          "$ref": "#/components/schemas/product"
        area:
          "$ref": "#/components/schemas/area"
        ticket:
          type: object
          properties:
            meta:
              type: object
              properties:
                version:
                  type: string
                  example: "1.0.0"
                requires_engine:
                  type: string
                  example: "1.0"
                template:
                  type: string
                  example: vrs-1
                available_rendering_options:
                  "$ref": "#/components/schemas/ticket_available_rendering_options"
            properties:
              type: object
              properties:
                barcode:
                  type: string
                identification_medium:
                  type: object
                unique_entitlement_id:
                  type: number
                  example: 1234567890
        ticket_created_at:
          type: string
          format: date-time
          example: '2022-12-14T11:00:00Z'
        valid_from:
          type: string
          format: date-time
          example: '2022-12-14T11:00:0Z'
        valid_until:
          type: string
          format: date-time
          example: '2022-12-14T12:30:00Z'
        sold_at:
          type: string
          format: date-time
          example: '2022-12-14T10:00:00Z'
        environment:
          "$ref": "#/components/schemas/environment"
    area:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-area-uuid
        properties:
          type: object
          properties:
            city_name:
              type: string
              example: Example Area Name
            local_zone_name:
              type: string
              example: Example Area Description
            relation_number:
              type: string
              description: Optional relation number (for VRR Tickets)
              example: R110000
              nullable: true
            price_level:
              type: string
              description: Optional price level (for VRR Tickets)
              example: A1
              nullable: true
          required:
            - city_name
            - local_zone_name
        type:
          type: string
          example: Feature
        geometry:
          type: object
          properties:
            type:
              type: string
              example: Polygon
              enum:
              - Polygon
              - MultiPolygon
            coordinates:
              type: array
              items:
                oneOf:
                - type: array
                  items:
                    type: array
                    items:
                      type: array
                      items:
                        type: number
                - type: array
                  items:
                    type: array
                    items:
                      type: array
                      items:
                        type: array
                        items:
                          type: number
                - type: array
                  items:
                    type: array
                    items:
                      type: array
                      items:
                        type: array
                        items:
                          type: number
    subscription:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-subscription-uuid
        activate:
          type: boolean
          example: true
        coupon_reactivatable:
          type: boolean
          example: true
        current_cycle_valid_from:
          type: string
          format: date-time
          example: '2023-01-31T23:00:000Z'
        current_cycle_valid_until:
          type: string
          format: date-time
          example: '2022-02-28T22:59:59Z'
        ordered_until:
          type: string
          format: date-time
          example: '2022-03-31T22:59:59Z'
        current_subscription_cycle:
          "$ref": "#/components/schemas/subscription_cycle"
        next_subscription_cycle:
          "$ref": "#/components/schemas/subscription_cycle"
        next_unordered_subscription_cycle:
          "$ref": "#/components/schemas/subscription_cycle"
        subscription_cycles:
          type: array
          items:
            "$ref": "#/components/schemas/subscription_cycle"
    subscription_cycle:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-cycle-uuid
        billable_item_id:
          type: string
          example: mobilitybox-billable-uuid
        product_id:
          type: string
          example: mobilitybox-product-uuid
        valid_from:
          type: string
          format: date-time
          example: '2023-01-31T23:00:000Z'
        valid_until:
          type: string
          format: date-time
          example: '2022-03-31T22:59:59Z'
        ordered:
          type: boolean
          example: false
        coupon_activated:
          type: boolean
          example: false
        ordered_at:
          type: string
          format: date-time
          example: '2023-01-31T23:00:000Z'
    ticket_possible_rendering_options:
      type: array
      items:
        type: string
        example: "rendering_engine"
        description: describes the possible options of a product how a ticket could be rendered
        enum:
          - rendering_engine
          - apple_wallet
          - google_wallet
          - mobility_wallet
    ticket_available_rendering_options:
      type: array
      items:
        type: string
        example: "rendering_engine"
        description: describes the available options for a ticket how it can be rendered
        enum:
          - rendering_engine
          - apple_wallet
          - google_wallet
          - mobility_wallet
    provider:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-provider-uuid
        short_name:
          type: string
          example: REVG
        long_name:
          type: string
          example: Rhein-Erft-Verkehrsgesellschaft mbH
        address:
          type: string
        vat_identification_number:
          type: string
    customer:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-customer-uuid
        address_lines:
          type: array
          items:
            type: string
            maxLength: 35
          minItems: 1
          maxItems: 5
        environment:
          "$ref": "#/components/schemas/environment"
    customer_create_params:
      type: object
      properties:
        customer:
          type: object
          properties:
            address_lines:
              type: array
              items:
                type: string
                maxLength: 35
              minItems: 1
              maxItems: 5
    billable_items:
      type: array
      items:
        "$ref": "#/components/schemas/billable_item"
    billable_item:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-billable-uuid
        provider_id:
          type: string
          example: mobilitybox-provider-uuid
        billable_collection_id:
          type: string
          description: ID of the billable collection that contains this billable item
          example: mobilitybox-collection-uuid
          nullable: true
        ordered_at:
          type: string
          format: date-time
        mobilitybox_product_id:
          type: string
          description: ID of the ordered product
          example: mobilitybox-product-uuid
        amount_in_cents:
          type: integer
          example: 1000
        currency:
          type: string
          example: EUR
        vat:
          type: integer
          example: 7
        environment:
          "$ref": "#/components/schemas/environment"
        invoice_id:
          type: string
          description: ID if the billable item was invoiced
          example: mobilitybox-invoice-uuid
        split:
          "$ref": "#/components/schemas/split"
    split:
      type: array
      description: a list of split items. Defines how the amount of the billable item is split between customers. The first element is the split item of the beneficiary of the ordered product.
      items:
        "$ref": "#/components/schemas/split_item"
    split_item:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-split-uuid
        customer_id:
          type: string
          example: mobilitybox-customer-uuid
        amount_in_cents:
          type: integer
          example: 1000
    billable_item_add_customer_params:
      type: object
      properties:
        customer_id:
          type: string
          example: mobilitybox-customer-uuid"
        billable_collection_id:
          type: string
          example: mobilitybox-collection-uuid
    billable_item_add_split_params:
      type: object
      properties:
        split:
          "$ref": "#/components/schemas/split"
        billable_collection_id:
          type: string
          example: mobilitybox-collection-uuid
    billable_collection:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-collection-uuid
        billable_item_ids:
          type: array
          items:
            type: string
            example: mobilitybox-billable-uuid
    billable_collection_create_params:
      type: object
      properties:
        billable_collection:
          type: object
          nullable: true
          properties:
            billable_item_ids:
              type: array
              items:
                type: string
                example: mobilitybox-billable-uuid
              minItems: 1
    billable_collection_add_billable_items_params:
      type: object
      properties:
        billable_item_ids:
          type: array
          items:
            type: string
            example: mobilitybox-billable-uuid
          minItems: 1
    create_invoice_params:
      type: object
      properties:
        subject:
          type: string
          example: Rechnung
        notes:
          type: string
        custom_text_before_table:
          type: string
        custom_text_after_table:
          type: string
    invoices:
      type: array
      items:
        "$ref": "#/components/schemas/invoice"
    invoice:
      type: object
      properties:
        id:
          type: string
          example: mobilitybox-invoice-uuid
        invoice_number:
          type: string
          example: 001-00001234
        invoice_pdf_url:
          type: string
          example: https://api.themobilitybox.com/api/v8/ticketing/invoices/mobilitybox-invoice-uuid/pdf-identifier.pdf
          description: URL to the pdf download of the invoice
        provider_id:
          type: string
          example: mobilitybox-provider-uuid
        subject:
          type: string
        notes:
          type: string
        custom_text_before_table:
          type: string
        custom_text_after_table:
          type: string
        customer_id:
          type: string
          example: mobilitybox-customer-uuid
        invoiced_at:
          type: string
          format: datetime
        invoice_items:
          "$ref": "#/components/schemas/invoice_items"
    invoice_items:
      type: array
      items:
        "$ref": "#/components/schemas/invoice_item"
    invoice_item:
      type: object
      properties:
        billable_item_id:
          type: string
          example: mobilitybox-billable-uuid
        customer_id:
          type: string
          example: mobilitybox-customer-uuid
        amount_in_cents:
          type: integer
          example: 1000
        split_id:
          type: string
          example: mobilitybox-split-uuid
    api_error:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    "API-Key via query parameter":
      type: apiKey
      in: query
      name: api_key
    "API-Key via HTTP-Header":
      type: http
      in: header
      scheme: bearer
security:
  - "API-Key via query parameter": []
  - "API-Key via HTTP-Header": []
paths:
  "/ticketing/areas.json":
    get:
      summary: Returns a list of available areas (where products are available).
      operationId: getAreas
      description: |
        Returns a list of available areas (where products are available).
        Contains a [GeoJSON](https://geojson.org/) representation of the geography data.
      tags:
      - Area
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/areas"
  "/ticketing/areas/{id}.json":
    get:
      summary: Retrieve an area by id
      operationId: getAreaById
      description: |
        Returns the details of an area for the ID given.
        Contains a [GeoJSON](https://geojson.org/) representation of the geography data.
      tags:
      - Area
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique area ID
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/area"
        '404':
          description: Area not found
  "/ticketing/products/search_by_area_id.json":
    get:
      summary: Retrieve all the products searching by area_id
      operationId: searchProductsByAreaId
      tags:
      - Product
      parameters:
        - name: area_id
          in: query
          required: true
          schema:
            type: string
          description: Unique area ID that retrieves only the products available in that area.
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/products"
  "/ticketing/products/search_by_city_name.json":
    get:
      summary: Retrieve all the products searching by city name
      operationId: searchProductsByCityName
      tags:
      - Product
      parameters:
        - name: city_name
          in: query
          required: true
          schema:
            type: string
          example: "Bonn"
          description: City name that retrieves only the products available in that city.
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/products"
  "/ticketing/products/search_by_location.json":
    get:
      summary: Retrieve all the products searching by location (latitude, longitude)
      operationId: searchProductsByLocation
      tags:
      - Product
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
          example: 50.733334
          description: Latitude name that is used to retrieve the products.
        - name: longitude
          in: query
          required: true
          schema:
            type: number
          example: 7.100000
          description: Latitude name that is used to retrieve the products.
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/products"
  "/ticketing/products/{id}.json":
    get:
      summary: Retrieve a product by id
      operationId: getProductById
      tags:
      - Product
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique product ID
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/product"
        '404':
          description: Product not found
  "/ticketing/orders.json":
    post:
      summary: Create an order for a list of products
      operationId: createOrder
      tags:
      - Order
      parameters:
        - $ref: '#/components/headers/Idempotency-Key'
      requestBody:
        description: |
          To create an order, a list of product IDs is needed (Maximum 10). `optional_order_reference` can be anything
          that you can decide to put as a reference on your side. It will be present inside the order in our systems.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_ids:
                  type: array
                  example: ["mobilitybox-product-37ff65b7-081f-46b7-9f39-5fcf68e100e6", "mobilitybox-product-dab84e4a-85d1-4ad6-b7b0-296f34274a20"]
                  minItems: 1
                  maxItems: 10
                optional_order_reference:
                  type: string
                  example: "My reference"
      responses:
        '201':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/createOrderResponse"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '404':
          description: At least one Product was not Found.
        '422':
          description: Validation of the request body has failed
  "/ticketing/orders/{id}.json":
    get:
      summary: Retrieve an order
      description: |
        Retrieve an order that has been previously created.
      tags:
      - Order
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique order ID - received after creating an order
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/orderResponse"
        '404':
          description: Order not found
  "/ticketing/coupons/{id}.json":
    get:
      summary: Retrieve a coupon
      tags:
      - Coupon
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique coupon ID - received after creating an order
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/coupon"
        '404':
          description: Coupon not found
  "/ticketing/coupons/{id}/activate.json":
    post:
      summary: Activate a coupon
      operationId: activateCoupon
      tags:
      - Coupon
      parameters:
        - $ref: '#/components/headers/Idempotency-Key'
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique coupon ID - received after creating an order
      security: []
      requestBody:
        description: |
          The identification medium of the person activating the coupon. **Needs to be a JSON Object that passes the identification_medium_schema validation inside the ordered product.**

          When you have an active subscription, you can reactivate your coupon with the `coupon_reactivation_key` returned by the ticket. To do so, you must pass it as `reactivation_key` instead of the `identification_medium`.

          Additionally, you can also pass `tariff_settings`. Please check out the [Tariff Settings Guide](/ticketing/documentation/tariff_settings) for detailed information.

          Additionally you can pass an `activation_start_datetime` for the initial activation, for example `2023-05-01T00:00:00+02:00`.<br>
          It defines the start when the ticket is valid. The datetime can not be before the coupon order time.
          Activating a coupon with a subscription will automatically set the ticket valid from to the datetime based on the passed `activation_start_datetime` and the `duration_definition` of the product.<br>
          For example, when activating a coupon with `duration_definition="calendar_month"` and passing as `activation_start_datetime="2023-05-15T12:40:00+02:00"`, it will set the ticket subscription start time and ticket valid from to `2023-05-01T00:00:00+02:00`.
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    identification_medium:
                      type: object
                      example: {photo_id_lite: {first_name: "Max", last_name: "Mustermensch", birth_date: "1990-05-30"}}
                    tariff_settings:
                      type: object
                      example: {tariffzones: ["mobilitybox-area-uuid1", "mobilitybox-area-uuid2", "mobilitybox-area-uuid3"]}
                    activation_start_datetime:
                      type: string
                      format: date-time
                      example: '2022-01-01T00:00:00Z'
                  required:
                    - "identification_medium"
                - type: object
                  properties:
                    reactivation_key:
                      type: string
                      description: The key returned by ticket API is used to reactivate coupon from a subscription
                  required:
                    - "reactivation_key"
              example:
                identification_medium: {photo_id_lite: {first_name: "Max", last_name: "Mustermensch", birth_date: "1990-05-30"}}
                tariff_settings: {german_postal_code: "12345"}
                activation_start_datetime: '2025-07-02T14:21:10+00:00'
      responses:
        '201':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket_id:
                    type: string
                    example: "mobilitybox-ticket-283037c1-e923-413b-ae86-25194e7f2e65"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '404':
          description: Coupon not found
        '422':
          description: Validation of the request body has failed
  "/ticketing/coupons/{id}/tariff_settings.json":
    post:
      summary: Add tariff settings
      operationId: addTariffSettings
      tags:
      - Tariff Settings
      description: |
        Add tariff settings to a coupon. When an ordered product has a tariff settings schema and requires some information, you must add this data with this request or while activating the coupon.
        Please check out the [Tariff Settings Guide](/ticketing/documentation/tariff_settings) for detailed information.
      parameters:
        - $ref: '#/components/headers/Idempotency-Key'
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique coupon ID - received after creating an order
      security: []
      requestBody:
        description: |
          The tariff settings must be a JSON object that passes the tariff_settings_schema validation within the ordered product.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tariff_settings:
                  type: object
                  example: {tariffzones: ["mobilitybox-area-uuid1", "mobilitybox-area-uuid2", "mobilitybox-area-uuid3"]}
              required:
                  - "tariff_settings"
              example:
                tariff_settings: {tariffzones: ["mobilitybox-area-uuid1", "mobilitybox-area-uuid2", "mobilitybox-area-uuid3"]}
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/coupon"
        '400':
          description: Malformed Query
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_error"
              examples:
                alread_activated:
                  value: {message: "Can't modify the tariff settings of an activated coupon"}
                  summary: Can't modify the tariff settings of an activated coupon
                not_eligible:
                  value: {message: "The ordered product of the coupon is not eligible for adding/removing tariff settings"}
                  summary: The ordered product of the coupon is not eligible for adding/removing tariff settings
        '404':
          description: Coupon not found
    delete:
      summary: Remove tariff settings
      operationId: removeTariffSettings
      tags:
      - Tariff Settings
      description: |
        Remove tariff settings from a coupon. When an ordered product has a tariff settings schema and you added some tariff settings before, you must remove this data with this request.
        Please check out the [Tariff Settings Guide](/ticketing/documentation/tariff_settings) for detailed information.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique coupon ID - received after creating an order
      security: []
      requestBody:
        description: |
          To remove only specific data of the tariff settings, you can pass the optional `tariff_settings_keys`, which contain single keys of the data you passed before.
          Without that, you remove all data.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tariff_settings_keys:
                  type: array
                  items:
                    type: string
                  example: ["key1", "key2"]
              example:
                tariff_settings_keys: ["key1", "key2"]
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/coupon"
        '400':
          description: Malformed Query
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_error"
              examples:
                alread_activated:
                  value: {message: "Can't modify the tariff settings of an activated coupon"}
                  summary: Can't modify the tariff settings of an activated coupon
                not_eligible:
                  value: {message: "The ordered product of the coupon is not eligible for adding/removing tariff settings"}
                  summary: The ordered product of the coupon is not eligible for adding/removing tariff settings
        '404':
          description: Coupon not found
  "/ticketing/subscriptions/{id}.json":
    get:
      summary: Retrieve a subscription
      tags:
      - Subscription
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique subscription ID - received after creating an order with a subscribable product
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/subscription"
        '404':
          description: Subscription not found
    delete:
      summary: Cancel a subscription
      description: It sets `active` of the subscription to false. After you cancel the subscription you can't reorder anymore. For all ordered subscription cycles, you can still receive the tickets.
      tags:
      - Subscription
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique subscription ID - received after creating an order with a subscribable product
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/subscription"
        '404':
          description: Subscription not found
  "/ticketing/subscriptions/{id}/reorder.json":
    post:
      summary: Reorder a subscription so the coupon can be reactivated again in the next cycle
      operationId: reorderSubscription
      tags:
      - Subscription
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique subscription ID - received after creating an order with a subscribable product
      requestBody:
        description: |
          You can pass a `subscription_cycle_id` to ensure you reorder a specific cycle.
          When you don't pass a `subscription_cycle_id`, the next unordered subscription cycle will be ordered.
        content:
          application/json:
            schema:
              type: object
              properties:
                subscription_cycle_id:
                  type: string
                  example: "mobilitybox-cycle-uuid"
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/subscription"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '404':
          description: The subscription was not found.
        '422':
          description: Validation of the request body has failed
  "/ticketing/orders/{id}/restore.json":
    post:
      summary: Restores coupons of an order
      description: |
        Restores all passed coupons of an order and returns new coupons. Also, check out the [detailed restore ticket explanation](https://developer.themobilitybox.com/ticketing/documentation/restore)
      tags:
      - Order
      - Coupon
      parameters:
        - $ref: '#/components/headers/Idempotency-Key'
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique order ID - received after creating an order
      requestBody:
        description: |
          A list of coupon IDs is needed to restore coupons for an order. Also, you have to pass the `restore_secret` of the order.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                coupon_ids:
                  type: array
                  example: ["mobilitybox-coupon-uuid-1", "mobilitybox-coupon-uuid-2"]
                restore_secret:
                  type: string
                  example: "mobilitybox-restore-secret-uuid"
      responses:
        '200':
          description: |
            success

            Returns the order with a new coupon for each original coupon you passed in the parameters. After that, you can activate the new coupons the usual way, by passing the identification medium.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/orderResponse"
  "/ticketing/tickets/{id}.json":
    patch:
      summary: Retrieve a ticket
      description: |
        Retrieve a ticket by passing the `id`.<br>
        **Attention! When the Coupon/Cycle was ordered before API v8 this API call will delete the ticket from our systems once you have received it.**<br>
        For more information about the [Ticket Data Storage Strategy documentation](/ticketing/documentation/data_storage_strategy)

        **Added:** `available_rendering_options` to ticket meta attributes
      operationId: patchTicket
      tags:
      - Ticket
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ticket"
        '202':
          description: A ticket with this ID is not ready yet
          content:
            application/json:
              schema:
                type: object
                example: {"message": "The ticket with this ID is not ready yet. Please try again in a few seconds."}
        '400':
          description: General Error, e.g., wrong API version
        '404':
          description: Ticket not found or already downloaded
          content:
            application/json:
              schema:
                type: object
                example: {"message": "A ticket with this ID has not yet been created or had already been downloaded."}
  "/ticketing/tickets/{ticket_id}/available_rendering_options.json":
    get:
      summary: Gets available rendering options for a given `ticket_id`.
      tags:
      - Ticket
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ticket_available_rendering_options"
        '404':
          description: Ticket not found
          content:
            application/json:
              schema:
                type: object
                example: {"message": "Couldn't find Ticket with 'id'=..."}
  "/ticketing/passes/apple_wallet/{ticket_id}.json":
    get:
      summary: Gets the link for the Apple Wallet pass for a given `ticket_id`.
      tags:
      - Apple Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string
                example: "https://api.themobilitybox.com/v8/ticketing/passes/apple_wallet/{ticket_id}.pkpass"
        '302':
          description: redirect to waiting page if the ticket is not ready yet for pass generation
          headers:
            Location:
              description: redirect URI
              schema:
                type: string
                format: uri
                example: "https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready?requested_format=json"
          content:
            text/plain:
              schema:
                type: string
                example: Found. Redirecting to "https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready?requested_format=json"
  "/ticketing/passes/apple_wallet/{ticket_id}.pkpass":
    get:
      summary: Gets the the Apple Wallet pass for a given `ticket_id` in pkpass format.
      tags:
      - Apple Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          headers:
            Content-Type:
              schema:
                type: string
                example: application/vnd.apple.pkpass
                enum:
                  - application/vnd.apple.pkpass
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="{ticket_id}.pkpass"; filename*=UTF-8''{ticket_id}.pkpass
          content:
            application/vnd.apple.pkpass:
              schema:
                description: the Pkpass File for Apple Wallet
                format: binary
        '302':
          description: redirect to waiting page if the ticket is not ready yet for pass generation
          headers:
            Location:
              description: redirect URI
              schema:
                type: string
                format: uri
                example: "https://api.themobilitybox.com/v8/ticketing/passes/apple_wallet/{ticket_id}/not_ready?requested_format=pkpass"
          content:
            text/plain:
              schema:
                type: string
                example: Found. Redirecting to "https://api.themobilitybox.com/v8/ticketing/passes/apple_wallet/{ticket_id}/not_ready?requested_format=pkpass"
  "/ticketing/passes/google_wallet/{ticket_id}.json":
    get:
      summary: Gets the link for the Google Wallet pass for a given `ticket_id`.
      tags:
      - Google Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string
                example: "https://pay.google.com/gp/v/save/{google_wallet_pass_jwt}"
        '302':
          description: redirect to waiting page if the ticket is not ready yet for pass generation
          headers:
            Location:
              description: redirect URI
              schema:
                type: string
                format: uri
                example: "https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready?requested_format=json"
          content:
            text/plain:
              schema:
                type: string
                example: Found. Redirecting to "https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready?requested_format=json"
  "/ticketing/passes/google_wallet/{ticket_id}":
    get:
      summary: Redirects to the Google Wallet Pass link for a given `ticket_id`
      tags:
      - Google Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '302':
          description: redirect to Google Wallet or to waiting page (when ticket is not ready yet for pass generation)
          headers:
            Location:
              description: redirect URI
              schema:
                type: string
                example: https://pay.google.com/gp/v/save/{google_wallet_pass_jwt} OR https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready
          content:
            text/plain:
              schema:
                type: string
                example: |
                  Found. Redirecting to https://pay.google.com/gp/v/save/{google_wallet_pass_jwt}
                  OR
                  Found. Redirecting to https://api.themobilitybox.com/v8/ticketing/passes/google_wallet/{ticket_id}/not_ready

  "/ticketing/passes/mobility_wallet/{ticket_id}.json":
    get:
      summary: Gets the link for the Mobility Wallet pass for a given `ticket_id`.
      tags:
      - Mobility Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string
                example: "https://mobilitywallet.themobilitybox.com/mobility_wallet/add_tickets?mobilitybox_ticket_ids={ticket_id}"
  "/ticketing/passes/mobility_wallet/{ticket_id}":
    get:
      summary: Redirects to the Mobility Wallet link for a given `ticket_id`
      tags:
      - Mobility Wallet
      parameters:
        - in: path
          name: ticket_id
          required: true
          schema:
            type: string
          description: Unique ticket ID - received after activating a coupon
      security: []
      responses:
        '302':
          description: redirect to Mobility Wallet
          headers:
            Location:
              description: redirect URI. Basically the App Link for Mobility Wallet to add a Ticket
              schema:
                type: string
                format: uri
                example: "https://mobilitywallet.themobilitybox.com/mobility_wallet/add_tickets?mobilitybox_ticket_ids={ticket_id}"
          content:
            text/plain:
              schema:
                type: string
                example: Found. Redirecting to https://mobilitywallet.themobilitybox.com/mobility_wallet/add_tickets?mobilitybox_ticket_ids={ticket_id}
  "/ticketing/providers/{id}.json":
    get:
      summary: Retrieve a provider
      description: Retrieve a provider by passing the `id`.
      tags:
      - Invoicing - Provider
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique provider ID
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/provider"
        '404':
          description: Provider not found
  "/ticketing/customers.json":
    post:
      summary: Create a customer, a maximum of 35 characters for each address_line
      tags:
      - Invoicing - Customer
      parameters:
        - $ref: '#/components/headers/Idempotency-Key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/customer_create_params"
      responses:
        '201':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
  "/ticketing/customers/{id}.json":
    get:
      summary: Retrieve a customer
      description: Retrieve a customer by passing the `id`.
      tags:
      - Invoicing - Customer
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique customer ID
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer"
        '404':
          description: Customer not found
  "/ticketing/billable_items/{id}.json":
    get:
      summary: Retrieve a billable_item
      description: Retrieve a billable_item by passing the `id`.
      tags:
      - Invoicing - Billable Item
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique billable_item id
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/billable_item"
        '404':
          description: Billable Item not found
    put:
      summary: Updates a billable item and adds Customer or Split
      description: You can add one customer to the billable item OR a set of split items (To split the amount between different customers). Additionally you can add the billable item to a billable collection.
      tags:
      - Invoicing - Billable Item
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique billable_item id
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/billable_item_add_customer_params"
              - "$ref": "#/components/schemas/billable_item_add_split_params"
              example: {
                billable_collection_id: "mobilitybox-collection-uuid",
                customer_id: "mobilitybox-customer-uuid",
                split: [
                  {
                    "customer_id": "mobilitybox-customer-uuid1",
                    "amount_in_cents": 2000
                  },
                  {
                    "customer_id": "mobilitybox-customer-uuid2",
                    "amount_in_cents": 1000
                  }
                ]
              }
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/billable_item"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: billable_item not found
  "/ticketing/billable_items/{id}/invoice.json":
    post:
      summary: creates an invoice for one billable item
      tags:
      - Invoicing - Billable Item
      description: |
        Creates one invoice for the passed billable item.

        __Note:__ The usage of this endpoint is only possible if the billable item has no or only one element in the `split` assigned. When there are multiple split items, you have to call the _invoice billable item for customer endpoint_
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_invoice_params"
      responses:
        '201':
          description: invoice created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/invoice"
        '303':
          description: billable_item was already invoiced. Redirect to the invoice.
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: billable_item not found


  "/ticketing/billable_items/{id}/invoice/{customer_id}.json":
    post:
      summary: creates an invoice for a customer of a billable item
      tags:
      - Invoicing - Billable Item
      description: |
        Creates an invoice for a billable item for the passed customer. The billable item must have a split with the passed customer.
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_invoice_params"
      responses:
        '201':
          description: invoice created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/invoice"
        '303':
          description: billable_item was already invoiced. Redirect to the invoice.
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: billable_item or customer not found

  "/ticketing/billable_collections.json":
    post:
      summary: creates a billable collection
      tags:
      - Invoicing - Billable Collection
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/billable_collection_create_params"
      responses:
        '201':
          description: billable collection created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/billable_collection"
  "/ticketing/billable_collections/{id}.json":
    get:
      summary: Retrieve a billable_collections
      description: Retrieve billable_collections by passing the `id`.
      tags:
      - Invoicing - Billable Collection
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique billable_collections id
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/billable_collection"
        '404':
          description: Billable Collection not found
  "/ticketing/billable_collections/{id}/billable_items.json":
    put:
      summary: add billing items to a billable collection
      tags:
      - Invoicing - Billable Collection
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/billable_collection_add_billable_items_params"
      responses:
        '201':
          description: billing items added
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/billable_collection"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: Billable Collection not found

  "/ticketing/billable_collections/{id}/invoice.json":
    post:
      summary: creates one or multiple invoices, including all billable items in a billable collection
      tags:
      - Invoicing - Billable Collection
      description: |
        Creates one or more invoices, including all unbilled billable items in a billable collection.
        If more than one provider issues the same billable items, it will create an invoice for each provider containing all the items they have issued.

         __Note:__ The usage of this endpoint is only possible if all billable items have no customer or only the same customer assigned via one split item. If there are multiple split items you have to call the _invoice billable collection for customer endpoint_
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_invoice_params"
      responses:
        '201':
          description: invoice/invoices created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/invoices"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: Billable Collection not found
  "/ticketing/billable_collections/{id}/invoice/{customer_id}.json":
    post:
      summary: creates one or multiple invoices for a billable collection for a specific customer
      tags:
      - Invoicing - Billable Collection
      description: |
        Create one or more invoices for the passed customer, including any unbilled billable items in a billable collection with a split item assigned to the passed customer.
        <br>If more than one provider issues the billable items, it will create an invoice for each provider containing all the items they issued.
        <br>When the passed customer is the beneficiary of some billable items and for some, it is not, then it will also create multiple invoices.
      parameters:
      - $ref: '#/components/headers/Idempotency-Key'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_invoice_params"
      responses:
        '201':
          description: invoice/invoices created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/invoices"
        '400':
          description: Malformed query. Usually, the parameters are not as expected.
        '422':
          description: Validation of the request body has failed
        '404':
          description: Billable Collection or Customer not found
  "/ticketing/invoices/{id}.json":
    get:
      summary: Retrieve an invoice
      description: Retrieve an invoice by passing the `id`.
      tags:
      - Invoicing - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique invoice ID
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/invoice"
        '404':
          description: Invoice not found
  "/ticketing/invoices/{id}.csv":
    get:
      summary: Retrieve an invoice CSV file
      description: Retrieve an invoice CSV file by passing the `id`.
      tags:
      - Invoicing - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique invoice ID
      responses:
        '200':
          description: success
          content:
            text/csv:
              {}
        '404':
          description: Invoice not found
  "/ticketing/invoices/{id}/{invoice_pdf_id}.pdf":
    get:
      summary: Retrieve an invoice PDF file
      description: Retrieve an invoice PDF file by passing the `invoice_pdf_id`.
      tags:
      - Invoicing - Invoice
      security: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique invoice ID
        - in: path
          name: invoice_pdf_id
          required: true
          schema:
            type: string
          description: Unique invoice pdf ID
      responses:
        '200':
          description: success
          content:
            application/pdf:
              {}
        '202':
          description: PDF with this ID is not ready yet
          content:
            application/json:
              schema:
                type: object
                example: {"message":"The Invoice is not ready yet. Please try again in a few seconds."}
        '404':
          description: Invoice not found
