openapi: 3.0.1
info:
  title: Meetch API
  description: |
    Meetch provides a REST API using JSON encoded response and standard HTTP response codes.

    To use this API, you need to have an organization account and a valid API Key.
  version: 1.0.0
servers:
  - url: 'https://api.preprod.ticketing.meetch.io/v1'
    description: "Ticketing"
  - url: 'https://api.preprod.travel.meetch.io/v1'
    description: "Travel"
  - url: 'https://api.preprod.maritime.meetch.io/v1'
    description: "Transport"
  - url: 'https://api.preprod.cover.meetch.io/v1'
    description: "Cover"
security:
  - apiKey: [ ]
tags:
  - name: Product
  - name: Subscription
  - name: Claim
  - name: Event
  - name: Channel
  - name: Webhook
  - name: Organization
    description: Webhooks can be use to receive events from the Meetch system without calling the API.


paths:
  #Organizations
  /organization/infos:
    get:
      tags:
        - Organization
      summary: Organization details
      description: |
        Returns company informations for the current organization.
        Includes children organizations when available.
        If the API key is attached to more than one organization, you need to specify the Organization-Id Header.
      operationId: organization-info
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OrganizationDetail'
                  - type: object
                    properties:
                      children:
                        type: array
                        description: Children organizations (only present if the organization has children)
                        items:
                          allOf:
                            - $ref: '#/components/schemas/OrganizationDetail'
                            - type: object
                              properties:
                                is_child:
                                  example: true
        "401":
          description: Organization required — the API key is not attached to a single organization. You need to specify the Organization-Id Header.
  /organizations:
    get:
      tags:
        - Organization
      summary: List organizations
      description: Returns all organizations attached to the API key, including children organizations.
      operationId: list-organizations
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
  /organizations/{id}:
    get:
      tags:
        - Organization
      summary: Get organization details
      description: Returns detailed informations about a specific organization. The API key must have access to the organization (directly or via its parent/children).
      operationId: get-organization
      parameters:
        - name: id
          in: path
          description: Organization ID (format `org_xxx`)
          required: true
          style: simple
          example: "org_abc123"
          schema:
            type: string
            pattern: "^org_[a-zA-Z0-9]+$"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDetail'
        "404":
          description: Organization not found or not accessible by this API key.

  #Products
  /products:
    get:
      tags:
        - Product
      summary: List products
      description: Returns all available products for the current organization.
      operationId: list-products
      parameters:
        - name: grids
          in: query
          description: Includes pricing grids.
          required: false
          style: form
          explode: true
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
  /products/{id}/grids:
    get:
      tags:
        - Product
      summary: List product grids
      description: Returns all available product pricing grids.
      operationId: list-grids
      parameters:
        - name: id
          in: path
          description: ID of the product
          required: true
          style: simple
          example: "prod_123abc"
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  grids:
                    type: array
                    items:
                      $ref: '#/components/schemas/Grid'
  /products/{id}/pricing/compute:
    get:
      tags:
        - Product
      summary: Compute the insurance amount
      description: |
        Compute a price for a given insured amount based on the insurance product contrat.

        :::info
        Consider using cache system to avoid multiple calls to this endpoint on your front-end integration.
        :::

      operationId: compute-pricing
      parameters:
        - name: id
          in: path
          description: ID of the product
          required: true
          style: simple
          example: "prod_123abc"
          schema:
            type: string
        - name: amount
          in: query
          description: Insured amount
          required: true
          style: form
          schema:
            type: number
            format: float
        - name: grid_id
          in: query
          description: In case of multiple pricing grids.
          required: false
          style: form
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                properties:
                  price:
                    type: number
                    format: float
                  taxes:
                    type: number
                    format: float
                example:
                  price: 6.80
                  taxes: 0.12

  #Subscriptions
  /subscriptions:
    get:
      tags:
        - Subscription
      summary: List subscriptions
      description: "Returns all subscriptions for the current organization."
      operationId: list-subscriptions
      parameters:
        - name: since
          in: query
          description: YYYY-MM-DD format
          required: false
          style: form
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          description: YYYY-MM-DD format
          required: false
          style: form
          schema:
            type: string
            format: date-time
        - name: order_reference
          in: query
          description: Distributor internal reference
          required: false
          style: form
          schema:
            type: string
        - name: reference
          in: query
          description: Meetch subscription's reference
          required: false
          style: form
          schema:
            type: string
        - name: include_items
          in: query
          description: Returns items in the response.
          required: false
          style: form
          schema:
            type: boolean
            default: false
        - name: status
          in: query
          description: Status of the subscriptions. You can pass multiple values separated with comma `,`
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
              enum: [ active, waiting_payment, archived ]
              default: active
        - name: limit
          in: query
          description: Limit
          required: false
          schema:
            type: integer
            default: 100
        - name: page
          in: query
          description: Limit
          required: false
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
    post:
      tags:
        - Subscription
      summary: Create a subscription
      description: Creates a new subscription attached to an insurance product.
      operationId: create-subscription
      requestBody:
        $ref: '#/components/requestBodies/Subscription'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
  /subscriptions/bulk:
    post:
      tags:
        - Subscription
      summary: Bulk subscriptions
      description: |
        In order to send multiple subscriptions data in a single request, you can use the Bulk mode.
        
        :::info
        This endpoint will returns HTTP code 200 even if some subscriptions are not created. 
        You can check the `errors` response to see which subscriptions are not created.
        :::

      operationId: create-subscription-bulk
      requestBody:
        $ref: '#/components/requestBodies/SubscriptionBulk'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  errors:
                    type: object
                    properties:
                      total:
                        type: number
                        format: int32
                        example: 3
                      references:
                        type: array
                        items:
                          type: object
                          additionalProperties:
                            type: string
                            example: Order Ref_X already existing
                    example:
                      total: 3
                      references:
                        - key: Order Ref_X already existing
                        - key: Order Ref_X already existing
                example:
                  subscriptions:
                    reference: reference
                    preferred_locale: fr_FR
                    buyer_email: example@meetch.io
                    buyer_country: FR
                    buyer_address: buyer_address
                    order_reference: ABC
                    buyer_phone: +33000000000
                    created_at: created_at
                    buyer_company: buyer_company
                    buyer_lastname: Maison
                    buyer_city: Paris
                    buyer_zipcode: 75000
                    order_date: 2024-11-01
                    buyer_date_of_birth: 1979-06-18
                    additional_data: { }
                    insurance_amount: 10
                    buyer_gender: M
                    product_id: 12
                    order_amount: 380
                    currency: EUR
                    items:
                      - event_date_end: 2026-03-12T15:19:21+00:00
                        event_place: Théatre St Martin
                        event_zipcode: "75005"
                        event_address: 5 rue du Somewhere 5th Arr.
                        label: 1 x Gold Ticket
                        event_date_start: 2026-02-12T15:19:21+00:00
                        holder_email: patrick-smith@exemple.com
                        number: "123456789"
                        event_tour: event_tour
                        holder_date_of_birth: 1964-01-29
                        additional_data: { }
                        event_id: event_id
                        event_type: concert
                        insured_amount: 0.8008282
                        refundable_amount: 0.8008282
                        insurance_amount: 6.0274563
                        event_city: Paris
                        price: 380
                        insurance_discount_amount: 10
                        event_country: FR
                        event_name: Best Band Live
                        holder_name: Patrick Smith
                      - event_date_end: 2026-03-12T15:19:21+00:00
                        event_place: Théatre St Martin
                        event_zipcode: "75005"
                        event_address: 5 rue du Somewhere 5th Arr.
                        label: 1 x Gold Ticket
                        event_date_start: 2026-02-12T15:19:21+00:00
                        holder_email: patrick-smith@exemple.com
                        number: "123456789"
                        event_tour: event_tour
                        holder_date_of_birth: 1964-01-29
                        additional_data: { }
                        event_id: event_id
                        event_type: concert
                        insured_amount: 0.8008282
                        refundable_amount: 0.8008282
                        insurance_amount: 6.0274563
                        event_city: Paris
                        price: 380
                        insurance_discount_amount: 10
                        event_country: FR
                        event_name: Best Band Live
                        holder_name: Patrick Smith
                    buyer_firstname: Alfred
                    status: active
                  errors:
                    total: 3
                    references:
                      - key: Order Ref_X already existing
                      - key: Order Ref_X already existing
  /subscriptions/{reference}:
    get:
      tags:
        - Subscription
      summary: Retrieve a subscription
      description: "Retrieve a subscription data from its reference"
      operationId: getSubscription
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
    put:
      tags:
        - Subscription
      summary: Update a subscription
      description: |
        Updates the specified subscription by setting the values of the parameters passed. 
        Other parameters not provided are left unchanged.

        **If there are changes in `items` attribute, you must send all updated AND existing items data.**
        
        **If the order amount has changed (increase or decrease):** 
        
        
        The insurance premium must be recalculated according to the new price: the additional amount must be invoiced or the difference refunded to the policyholder, and the information relating to the change in the insurance amount must be sent.
        
        
        **<u>The premium must always correspond to the value of the order!</u>**
        
        :::note
        You cannot change a subscription’s ID, order_reference, currency or product_id.
        :::
      operationId: updateSubscription
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/UpdateSubscription'
      responses:
        "200":
          description: Success
    delete:
      tags:
        - Subscription
      summary: Cancel a subscription
      description: |
        Cancels a customer’s subscription immediately. In case of a plan, the customer will not be charged again for the subscription.<br></br><br></br>
        
        :::warning
        **Use this endpoint only in case of error.**
        
        It may be unavailable depending on the environment you are on.
        :::

      operationId: cancel-subscription
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  delete:
                    example: true
  /subscriptions/{reference}/attachments:
    get:
      tags:
        - Subscription
      summary: List documents
      description: List all documents attached to subscription.
      operationId: list-subscription-attachments
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
                #example:
                #  attachments:
                #    - filename: filename
                #      refund_request: true
                #      proof_type: proof_type
                #      file_type: file_type
                #      created_at: created_at
                #      id: id
                #      url: http://example.com/aeiou
                #    - filename: filename
                #      refund_request: true
                #      proof_type: proof_type
                #      file_type: file_type
                #      created_at: created_at
                #      id: id
                #      url: http://example.com/aeiou
  /subscriptions/{reference}/certificate:
    get:
      tags:
        - Subscription
      summary: Insurance certificate
      description: Returns the insurance certificate of a subscription.
        If you want to retrieve the insurance certificate only, you can use this endpoint
      operationId: get-subscription-certificate
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
        "404":
          description: The certificate doesn't exist for this subscription
  /subscriptions/{reference}/urls:
    get:
      tags:
        - Subscription
      summary: Subscription forms URLs
      description: Returns the URLs of a subscription's organization.
        You can provide these URLs to users.
      operationId: get-subscription-urls
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: include_credentials
          in: query
          description: The URLs will be pre-filled with a token query parameter, allowing the user to log in directly to the form.
          required: false
          style: form
          schema:
            type: boolean
            default: 0
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_url:
                    description: "Personal space where the user can find all its documents and warranties."
                    type: string
                    example: "https://organization.account.meetch.io/ticketing"
                  claim_form_url:
                    description: "The main form for using insurance/refund service and claim a refund."
                    type: string
                    example: "https://organization.claim.meetch.io/ticketing"
                  repeal_form_url:
                    description: "The user may cancel the insurance during the legal period (14 days)."
                    type: string
                    example: "https://organization.repeal.meetch.io/ticketing"

  #Claim
  /subscriptions/{reference}/issues:
    get:
      tags:
        - Claim
      summary: List claims
      description: List requests attached to a subscription.
        
        A Claim is a request to Meetch to reimburse a customer for covered loss or policy event in accordance with the contract.
      operationId: list-claims
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      $ref: '#/components/schemas/Claim'
                example:
                  issues:
                    - refusal_reason: refusal_reason
                      order_reference: order_reference
                      target_currency: target_currency
                      payment_mode_id: payment_mode_id
                      created_at: created_at
                      status_formatted: status_formatted
                      requested_amount: 0.8008282
                      reason_category: reason_category
                      additional_data: { }
                      reason_key: reason_key
                      issue_date: issue_date
                      subscription_reference: subscription_reference
                      refund_mode_selected: refund_mode_selected
                      processed_at: processed_at
                      refund_amount: 6.0274563
                      comment: comment
                      currency: currency
                      id: id
                      payment_mode_method: payment_mode_method
                      status: draft
                    - refusal_reason: refusal_reason
                      order_reference: order_reference
                      target_currency: target_currency
                      payment_mode_id: payment_mode_id
                      created_at: created_at
                      status_formatted: status_formatted
                      requested_amount: 0.8008282
                      reason_category: reason_category
                      additional_data: { }
                      reason_key: reason_key
                      issue_date: issue_date
                      subscription_reference: subscription_reference
                      refund_mode_selected: refund_mode_selected
                      processed_at: processed_at
                      refund_amount: 6.0274563
                      comment: comment
                      currency: currency
                      id: id
                      payment_mode_method: payment_mode_method
                      status: draft
    post:
      tags:
        - Claim
      summary: Open a claim
      description: Open a claim from a subscription. You can request a refund for a specific amount.
      operationId: openIssue
      parameters:
        - name: reference
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/Issue'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
  /issues/{id}:
    get:
      tags:
        - Claim
      summary: Get a claim
      operationId: getClaim
      parameters:
        - name: id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
  /cancellations:
    get:
      tags:
        - Claim
      summary: List cancelled items
      description: |
        Returns all refunded items from a specific date.

        You can manage items cancelled by the insurance on your side (access control).

        :::note
        [Webhooks](./create-webhook) can be useful to receive real-time updates about claims.
        :::

      operationId: list-cancellations
      parameters:
        - name: since
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
            description: DateTime (ISO 8601 preferred)
            format: date-time
        - name: until
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
            description: DateTime (ISO 8601 preferred)
            format: date-time
        - name: limit
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: number
            format: int32
        - name: offset
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: number
            format: int32
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    $ref: '#/components/schemas/Item'
  /subscriptions/{reference}/notify:
    post:
      tags:
        - Claim
      summary: Item status update
      description: |
        Notify Meetch about the status of an item.

        Use cases :

        * Mark a ticket as "scanned"
        * Mark a ticket as "refunded by the vendor"
        * Notify event cancellation on a single ticket (without using `items.event_id`)

        :::info
        If you want to notify a global event cancellation using a specific `event_id`, see [mark event as cancelled](./cancel-event).
        :::

      operationId: update-item-status
      parameters:
        - name: reference
          in: path
          description: Reference of the subscription
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - notification
              properties:
                item:
                  type: string
                  description: |
                    Single item `number` to update.
                    Provide either `item` or `items`.
                  example: 'ABC123'
                items:
                  type: array
                  description: |
                    Items `number` to update.
                    Provide either `item` or `items`.
                  items:
                    type: string
                  example: [ 'ABC123', 'ABC124' ]
                notification:
                  type: string
                  description: |
                    The notification type.
                    - `scanned` - If the ticket has been used by the customer
                    - `refunded_by_organization` - If the ticket has been refunded directly by the vendor/organization
                    - `event_cancelled` - If the event is cancelled.
                  enum: [ 'scanned', 'refunded_by_organization', 'event_cancelled' ]
                set:
                  type: boolean
                  description: |
                    Whether to set or unset the status.
                    - `true` (default) - Apply the status (e.g. mark as scanned/refunded).
                    - `false` - Remove the previously applied status.

                    Not applicable to `event_cancelled`, which is ignored when `set` is `false`.
                  default: true
                notification_date:
                  type: string
                  description: Date of the update.
                  format: date-time
                  example: 2025-01-01
      responses:
        "200":
          description: Success

  #Events
  /events:
    post:
      tags:
        - Event
      summary: Create an event
      description: In order to manage events before creating subscriptions, you can create events for your organization.
      operationId: create-event
      requestBody:
        $ref: '#/components/requestBodies/Event'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    get:
      tags:
        - Event
      summary: List events
      description: Returns all existing events for the current organization and its children of any. If organization is not provided, all events of all organizations are returned.
      operationId: list-events
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
  /events/{id}:
    get:
      tags:
        - Event
      summary: Get an event
      description: |
        Returns the event informations.
        
        :::note
        In order to use your own IDs from `external_event_id`, please contact us.
        :::

      operationId: get-event
      parameters:
        - name: id
          in: path
          description: "The Event ID."
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    put:
      tags:
        - Event
      summary: Update an event
      description: Update Event data
      operationId: update-event
      requestBody:
        $ref: '#/components/requestBodies/Event'
      parameters:
        - name: id
          in: path
          description: "Event ID"
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/Event'
  /events/{id}/cancel:
    put:
      tags:
        - Event
      summary: Cancel an event
      description: |
        Mark event as cancelled from the vendor.

        :::warning
        Marking an event as cancelled may prevent associated refund requests.
        :::
      operationId: cancel-event
      parameters:
        - name: id
          in: path
          description: "Event ID to cancel"
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Success

  #Channel
  /channels:
    post:
      tags:
        - Channel
      summary: Create a channel
      description: Creates a channel associated to the current organization.
      operationId: create-channel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Channel'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
    get:
      tags:
        - Channel
      summary: List channels
      description: List all channels associated to the current organization.
      operationId: list-channels
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  channels:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
  /channels/{id}:
    get:
      tags:
        - Channel
      summary: Get a channel
      description: Returns a specific channel.
      operationId: get-channel
      parameters:
        - name: id
          in: path
          description: "The identifier of the channel"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
    put:
      tags:
        - Channel
      summary: Update channel
      description: Update a channel. Only the name can be modified.
      operationId: update-channel
      parameters:
        - name: id
          in: path
          description: The identifier of the channel
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - channel_name
              properties:
                channel_name:
                  type: string
                  description: The new name of the channel
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  channel:
                    $ref: '#/components/schemas/Channel'
    delete:
      tags:
        - Channel
      summary: Delete a channel
      operationId: delete-channel
      parameters:
        - name: id
          in: path
          description: The identifier of the channel
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success

  #Webhooks
  /webhooks:
    get:
      tags:
        - Webhook
      summary: List webhooks
      description: List all active webhook subscriptions.
      operationId: list-webhooks
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks_subscription:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
    post:
      tags:
        - Webhook
      summary: Create a webhook
      operationId: create-webhook
      description: |
        Create a webhook subscription to receive events from Meetch ([list of allowed events](/api-specifications/webhooks#available-event-types)). You can subscribe to multiple events.

        :::note[Test your webhook integration]
        You can trigger a test event from the manager's connector page.
        :::

      requestBody:
        $ref: "#/components/requestBodies/Webhook"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
  /webhooks/{id}:
    get:
      tags:
        - Webhook
      summary: Get webhook
      description: Returns details about the webhook subscription.
      operationId: get-webhook
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: ID of the webhook
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks_subscription:
                    $ref: '#/components/schemas/Webhook'
    put:
      tags:
        - Webhook
      summary: Update webhook
      description: Update a webhook subscription.
      operationId: update-webhook
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: ID of the webhook
        - name: url
          in: query
          description: Your url
          required: false
          example: "https://your.url"
          schema:
            type: string
        - name: events
          in: query
          required: false
          description: Format -> ["event.name", "event2.name"]
          example: [ 'subscription.created', 'claim.refused' ]
          schema:
            type: string
        - name: signing_key
          in: query
          description: Signing Key
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
    delete:
      tags:
        - Webhook
      summary: Delete webhook
      description: Delete a webhook subscription. You will not receive any more events.
      operationId: delete-webhook
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: ID of the webhook to delete
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                properties:
                  message:
                    example: "Your webhook subscription has been deleted"

#Components
components:
  schemas:
    Product:
      type: object
      description: A Product is associated to your Meetch contract, including a pricing table and legal documents.
      properties:
        id:
          type: string
          description: "Meetch identifier of the product"
          example: "prod_abc123"
        title:
          type: string
          description: Title of the product
        long_title:
          type: string
          description: Long title of the product
        category:
          type: string
          description: "Category of the insurance ('cancellation', 'product'...)"
        computing_mode:
          type: string
          description: If the premium amount is computed per item or on the global
            subscription amount
          enum:
            - ticket
            - subscription
        checkout_mode:
          type: string
          enum:
            - unique
            - split
        deleted:
          type: boolean
        police_contract_number:
          type: string
          description: Insurer contract number
        insurance_company:
          type: string
          description: Name of the insurance company
        organization_name:
          type: string
          description: Name of the organization
      example:
        id: "prod_1234abc"
        parent: null
        title: "Meetch Insurance"
        long_title: "My event Meetch cancellation insurance"
        category: "cancellation"
        computing_mode: "ticket"
        checkout_mode: "unique"
        deleted: false
        police_contract_number: "AB-123456"
        insurance_company: "Insurance Company"
        organization_name: "My Company"
    Subscription:
      description: A Subscription represents the creation of an insurance contract by Meetch issued to a customer.
      required:
        - buyer_email
        - buyer_firstname
        - buyer_lastname
        - items
        - order_amount
        - order_date
        - order_reference
      type: object
      properties:
        product_id:
          type: string
          description: Identifier of the insurance product.
          example: prod_abc123
        reference:
          type: string
          minLength: 8
          maxLength: 12
          readOnly: true
          description: Meetch reference of the subscription
          example: 11223344
        order_reference:
          type: string
          maxLength: 128
          description: Order reference made on the vendor side
          example: ORD_123ABC
        order_date:
          type: string
          description: Date of the order on the vendor side (ISO 8601 preferred)
          example: 2024-11-01 17:35
        status:
          type: string
          readOnly: true
          enum:
            - active
            - archived
            - waiting_payment
            - incomplete
        paid:
          type: boolean
          description: If not paid, the status will be set to `waiting_payment` and the insurance contract will not be active.
          default: true
          writeOnly: true
        currency:
          type: string
          description: ISO 4217 currency code (3 chars)
          example: EUR
          default: EUR
        preferred_locale:
          type: string
          description: |
            Buyer language (en_US, fr_FR, fr). 
            This locale will be used in emails and insurance certificate.
          example: fr_FR
        insurance_amount:
          type: number
          description: The total cost of the insurance paid by the buyer.
          format: float
          example: 10
        order_amount:
          type: number
          description: |
            The total cost of the customer order (insurance + items). 
            This amount is provided for information only and is *not* used to calculate the refund.
          format: float
          example: 380
        items:
          type: array
          description: List of insured items.
          items:
            $ref: '#/components/schemas/Item'
        buyer_gender:
          type: string
          maxLength: 10
          description: Buyer gender
          example: M
        buyer_firstname:
          type: string
          maxLength: 50
          description: Buyer firstname (optional if `buyer_company` is set)
          example: John
        buyer_lastname:
          type: string
          maxLength: 50
          description: Buyer lastname (optional if `buyer_company` is set)
          example: Doe
        buyer_company:
          type: string
          maxLength: 50
          description: Buyer company
          example: Company
        buyer_email:
          type: string
          maxLength: 100
          description: Buyer email
          format: email
          example: example@meetch.io
        buyer_phone:
          type: string
          maxLength: 20
          description: Buyer phone
          example: "+33601020304"
        buyer_address:
          type: string
          maxLength: 100
          description: Buyer address
          example: "Allée Napoléon III"
        buyer_country:
          type: string
          minLength: 2
          maxLength: 2
          description: Buyer country code (ISO 3166 2 chars)
          example: "FR"
        buyer_city:
          type: string
          maxLength: 50
          description: Buyer city
          example: "Bourges"
        buyer_zipcode:
          type: string
          maxLength: 10
          description: Buyer zipcode
          example: "18000"
        buyer_date_of_birth:
          type: string
          description: Buyer birthdate (ISO 8601)
          format: date-time
          example: 1979-06-18
        created_at:
          type: string
          readOnly: true
          description: Creation date (ISO 8601)
          format: date-time
          example: 2024-02-14T15:19:21
        additional_data:
          type: object
          description: You can use this parameter to attach any key-value data.
          example:
            key: value
    Item:
      description: |
        An Item is directly attached to a subscription. It represents an insured object that can be reimbursed by the insurance company.   

        :::info
        Properties `event_*` and `holder_*` are useful for event cancellation insurance only.
        :::

      required:
        - insurance_amount
        - label
        - number
        - price
      type: object
      properties:
        number:
          type: string
          maxLength: 128
          description: Number / unique reference / ticket barcode
          example: "123456789"
        label:
          type: string
          maxLength: 100
          description: "Description of the item (eg. Cat, Localization etc)"
          example: "Gold Ticket"
        price:
          type: number
          description: Unit price of the item
          format: float
          example: 380
        insured_amount:
          type: number
          description: Insured amount, if different from price.
          format: float
        refundable_amount:
          type: number
          description: Refundable amount for this item.
          format: float
          readOnly: true
        insurance_amount:
          type: number
          description: |
            The insurance amount paid by the buyer for this item. 
            *Optional in case of global subscription calculation*
          format: float
        insurance_discount_amount:
          type: number
          description: |
            Discount applied to the insurance amount.
          format: float
        event_id:
          type: string
          description: Existing event ID. You don't need to specify other `event_` properties.
        event_name:
          type: string
          maxLength: 100
          description: Event name / Hotel name
          example: Best Band Live
        event_date_start:
          type: string
          description: Event start date (ISO 8601)
          format: date-time
          example: 2026-02-12T15:19:21+00:00
          nullable: true
        event_date_end:
          type: string
          description: Event end date (ISO 8601)
          format: date-time
          example: 2026-03-12T15:19:21+00:00
          nullable: true
        event_address:
          type: string
          maxLength: 100
          description: Event address
          example: 5 rue du Somewhere 5th Arr.
          nullable: true
        event_zipcode:
          type: string
          maxLength: 10
          description: Event zipcode
          example: "75005"
          nullable: true
        event_city:
          type: string
          maxLength: 100
          description: Event city
          example: Paris
          nullable: true
        event_place:
          type: string
          maxLength: 100
          description: "Event location, place name, precision (e.g Accor Hotel Arena, Staples Center)"
          example: Théatre St Martin
          nullable: true
        event_type:
          type: string
          maxLength: 50
          description: "Event type (concert, festival, show...)"
          example: concert
          nullable: true
        event_tour:
          type: string
          maxLength: 100
          description: Event tour
          nullable: true
        event_country:
          type: string
          maxLength: 2
          description: ISO 3166 country code (2 chars)
          example: FR
          nullable: true
        holder_name:
          type: string
          maxLength: 100
          description: Name of the item holder
          example: Patrick Smith
        holder_email:
          type: string
          maxLength: 100
          description: Email of the item holder
          example: patrick-smith@exemple.com
        holder_date_of_birth:
          type: string
          description: Birthdate of the item holder (YYYY-MM-DD)
          format: date
          example: 1964-01-29
        quantity:
          type: integer
          minimum: 1
          default: 1
          description: Quantity of this item
        pack:
          type: integer
          minimum: 0
          default: 0
          description: Pack identifier
        point_of_sale:
          type: string
          description: Point of sale identifier
        support:
          type: string
          description: Support type identifier
        additional_data:
          type: object
          description: You can use this parameter to attach any key-value data.
          example:
            key: value
      example:
        label: Gold Ticket
        number: 123456789
        event_name: Best Band Live
        event_date_start: 2026-02-12T15:19:21+00:00
        event_date_end: 2026-03-12T15:19:21+00:00
        event_place: Théatre St Martin
        event_zipcode: "75005"
        event_address: 5 rue du Somewhere 5th Arr.
        event_city: Paris
        event_country: FR
        event_type: concert
        insurance_amount: 5
        price: 100
    Claim:
      title: Claim (refund request)
      description: A Claim is a request to Meetch to reimburse a customer for covered loss or policy event in accordance with the contract.
      type: object
      properties:
        id:
          type: string
          description: Issue identifier
          example: "iss_1234abc"
          readOnly: true
        subscription_reference:
          type: string
          description: Unique reference of the subscription
          example: 11223344
          readOnly: true
        order_reference:
          type: string
          description: Subscription's order reference - made on the vendor side
          example: ORD_123ABC
          readOnly: true
        reason_key:
          type: string
          maxLength: 30
          description: Claim's reason
          example: professional, tickets-theft, insured-corporal-accident
        reason_category:
          type: string
          maxLength: 30
          description: Claim's reason category
          example: cancellation
        comment:
          type: string
          maxLength: 255
          description: Claim's comment by the customer
        status:
          type: string
          readOnly: true
          enum:
            - draft
            - open
            - refund
            - refund_repeal
            - uncomplete
            - refused
            - closed
        status_formatted:
          type: string
          description: Localized status label.
          example: Refunded
        created_at:
          type: string
          description: Creation date of the claim.
          format: date-time
          readOnly: true
          example: 2025-02-14T15:19:21Z
        issue_date:
          type: string
          description: Date of the declared issue.
          format: date-time
          example: 2025-02-14T15:19:21Z
        processed_at:
          type: string
          description: Processing date by an operator. The claim can be marked as accepted or refused.
          format: date-time
          readOnly: true
          example: 2025-02-14T15:19:21Z
        requested_amount:
          type: number
          description: Amount requested by the customer
          format: float
        refund_amount:
          type: number
          description: Amount refunded
          readOnly: true
          format: float
        currency:
          type: string
          maxLength: 3
          description: Subscription currency
          format: currency
          readOnly: true
        target_currency:
          type: string
          format: currency
          maxLength: 3
          description: Payment mode currency. If different from the subscription currency.
        refusal_reason:
          type: string
          description: "Refusal reason, in case the claim is refused by an operator"
          readOnly: true
        payment_mode_id:
          type: string
          description: Identifier of the payment mode in order to refund
          readOnly: true
        payment_mode_method:
          type: string
          description: Associated payment method name
          readOnly: true
        refund_mode_selected:
          description: Depending of the insurance contract, it can a full refund, 70% refund or a repeal.
          type: string
          enum: [ 70, 100, repeal ]
        open:
          description:
            To prepare refund request without processing it, you can set this parameter to `false`.
            It can be useful to send attachment document.
          type: boolean
          writeOnly: true
          default: true
        additional_data:
          type: object
          description: You can use this parameter to attach any key-value data.
    Attachment:
      type: object
      properties:
        id:
          type: string
          description: Attachment ID
          example: "doc_1234abc"
        url:
          type: string
          description: Public URL
          format: url
          maxLength: 255
          example: https://example.com/my-document
        filename:
          type: string
          description: The name of the file
          maxLength: 50
          example: "my-document.pdf"
        file_type:
          type: string
          maxLength: 30
          description: "The mimetype of the file"
          example: "application/pdf"
        proof_type:
          type: string
          description: Attachment type ('contract' or custom proof document)
          readOnly: true
        refund_request:
          type: boolean
          description: If the document has been created from a claim.
          default: false
        created_at:
          type: string
          description: Creation date
          format: date-time
          readOnly: true
          example: 2025-02-14T15:19:21Z
    Event:
      type: object
      description: An event can be represented by a stay, a show, a journey or any insured event containing a place and a date.
      properties:
        id:
          type: string
          description: Event ID
          example: "ev_XQ4peN02vn7r"
          readOnly: true
        name:
          type: string
          maxLength: 50
          description: The name of the event/venue
          example: Best Band Live
        place:
          type: string
          maxLength: 50
          description: Location/Place name of the venue
          example: Staples Center
        tour:
          type: string
          maxLength: 50
          description: Name of the show tour
        event_type:
          type: string
          maxLength: 30
          description: "Category of the event. (e.g `show`, `festival`, `accommodation`...)"
        address:
          type: string
          maxLength: 128
          example: 123 rue de Rivoli
        zipcode:
          type: string
          maxLength: 10
          example: "75001"
        city:
          type: string
          maxLength: 50
          example: Paris
        date_start:
          type: string
          description: Event start date (ISO 8601)
          format: date-time
          example: 2025-02-14T15:19:21Z
        date_end:
          type: string
          description: Event end date (ISO 8601)
          format: date-time
          example: 2025-02-14T15:19:21Z
        lat:
          type: number
          description: Latitude
          format: float
        lng:
          type: number
          description: Longitude
          format: float
        timezone:
          type: string
          description: Event Timezone
          format: timezone
          example: Europe/Paris
        external_event_id:
          type: string
          description: Vendor's event ID
          example: "12345"
        status:
          type: string
          enum:
            - enabled
            - cancelled
            - draft
    Channel:
      title: Channel
      description: A channel is used to tag the source of subscriptions. These channels can be used to filter the data.
      type: object
      properties:
        channel_identifier:
          type: string
          maxLength: 30
          description: The identifier of the channel. The identifier should be unique and respect the following format `^[a-z0-9-]+$`.
          example: physical-store
        channel_name:
          type: string
          maxLength: 50
          description: The name of the channel
          example: Physical Store
        created_at:
          type: string
          description: Creation date of the channel
          format: date-time
          example: 2025-02-14T15:19:21Z
          readOnly: true
    Organization:
      title: Organization
      description: Vendor's summary information
      type: object
      properties:
        id:
          type: string
          maxLength: 30
          description: The identifier of the vendor.
          example: org_abc123
          readOnly: true
        name:
          type: string
          maxLength: 50
          description: The name of the vendor as a slug.
          example: my-organization
        public_name:
          type: string
          maxLength: 50
          description: The formatted name of the vendor.
          example: My Organization's public name
        url:
          type: string
          maxLength: 255
          description: Vendor's website URL.
        created_at:
          type: string
          description: Creation date of the organization.
          format: date-time
          readOnly: true
          example: 2025-02-14T15:19:21Z
        terms:
          type: string
          description: Terms and conditions.
        is_child:
          type: boolean
          description: If the vendor has a parent organization.
          readOnly: true
          example: false
    OrganizationDetail:
      title: Organization Detail
      description: Vendor's detailed information including branding and customization fields.
      allOf:
        - $ref: '#/components/schemas/Organization'
        - type: object
          properties:
            primary_color:
              type: string
              description: Primary color (hex).
              example: "#1a73e8"
            secondary_color:
              type: string
              description: Secondary color (hex).
              example: "#ffffff"
            gradient1:
              type: string
              description: First gradient color.
            gradient2:
              type: string
              description: Second gradient color.
            image_cover:
              type: string
              description: URL of the vendor's cover image.
              readOnly: true
            image_logo:
              type: string
              description: URL of the vendor's logo.
              readOnly: true
            image_icon:
              type: string
              description: URL of the vendor's icon.
              readOnly: true
            thumbnail:
              type: string
              description: URL of the vendor's thumbnail.
              readOnly: true
    Grid:
      title: Pricing Grid
      description: Defines a pricing grid used to calculate insurance costs based on insured amounts.
      type: object
      properties:
        id:
          type: string
          maxLength: 30
          description: The identifier of the pricing grid.
          example: grid_abc123
          readOnly: true
        name:
          type: string
          maxLength: 50
          description: Human-readable name of the pricing grid.
          example: Insurance product grid 2025
        currency:
          type: string
          format: currency
          example: "EUR"
        max_up_to:
          type: number
          description: Upper insured amount limit to which this pricing grid applies.
        max_included:
          type: boolean
          description: Indicates whether the upper price limit is included in this grid range. If false, the limit belongs to the next range.
        unit_label:
          type: string
          description: Optional label describing the insured unit used for pricing calculations.
          example: "montant assuré"
        pricing:
          type: array
          description: List of pricing ranges composing the grid.
          items:
            $ref: '#/components/schemas/PricingGridItem'
        period_validity_end:
          type: string
          format: date-time
          description: End date and time after which this pricing grid is no longer valid.

    PricingGridItem:
      title: PricingGridItem
      description: Defines a pricing rule for a specific insured amount range.
      type: object
      properties:
        up_to:
          type: number
          description: Upper insured amount limit for this pricing range.
          example: 10000
        relative_amount:
          type: number
          description: Insurance price per insured unit. For example, a 9% rate is represented as 0.09 per insured unit.
          example: 0.09
        absolute_amount:
          type: number
          description: Fixed insurance price applied for this pricing range, regardless of the insured amount.
    Webhook:
      title: Webhook
      description: Webhooks can be use to receive events from the Meetch system without calling the API.
      type: object
      properties:
        id:
          type: string
          example: wh_15WgnNXJBmZN
        url:
          type: string
          maxLength: 255
          description: Your URL
          example: https://your-url.com/webhook
        events:
          type: array
          description: List of events subscribed
          items:
            type: string
            enum: [
              'subscription.created',
              'claim.created',
              'claim.refused',
            ]
          example:
            [ "subscription.created", "claim.processed" ]

  requestBodies:
    Subscription:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Subscription'
    SubscriptionBulk:
      content:
        application/json:
          schema:
            type: object
            properties:
              subscriptions:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
    UpdateSubscription:
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  type: object
                  example:
                    label: Smartphone
                    price: 250.99
                    type: object
                    additional_data:
                      label: value
              buyer_email:
                example: example2@meetch.io
              buyer_phone:
                example: 33601020304
    Attachment:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Attachment'
    Issue:
      content:
        application/json:
          schema:
            properties:
              issue_date:
                type: string
                format: date-time
              attachments:
                type: array
                example:
                  - proof_type: Contrat d'annulation
                    filename: https://example.com
                  - proof_type: Fichier de test
                    filename: test.txt
                    filecontent: VGVzdCBlbmNvZGVkIGZpbGUu
                    file_type: text/plain
                items:
                  $ref: '#/components/schemas/Attachment'
              comment:
                type: string
                example: Lorem Ipsum Dolor Sit Amer
              open:
                type: boolean
                example: false
    NotifyItem:
      content:
        application/json:
          schema:
            example:
              - items: [ 'ABC123', 'ABC124' ]
                notification: scanned
                notification_date: 2023-12-01T00:00:00.000Z
    Event:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Event'
    Webhook:
      content:
        application/json:
          schema:
            type: object
            properties:
              url:
                type: string
                maxLength: 255
                description: Your url
                example: "https://your.url"
              events:
                type: array
                description: Events you want to subscribe to ([list of allowed events](/api-specifications/webhooks/#available-event-types)).
                items:
                  type: string
                  enum: [ 'subscription.created', 'subscription.updated', 'subscription.archived', 'claim.opened', 'claim.processed', 'claim.refunded', 'claim.refused' ]
              signing_key:
                type: string
                maxLength: 128
                example: "your-signing-key"
                description: Signing Key to secure your webhook ([how to secure your webhooks](/api-specifications/webhooks/#webhook-signature))
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
