Ticketing

Introduction

🔗 To know how Meetch works, see How does Meetch work?

🔗 For front-end integration information, see Front-end integration

🔗 For transfer subscriptions methods, see Transfer subscriptions to Meetch

🔗 For transfer premium calculation information, see Premium calculation

API: Main endpoints

🔗 For authentication instructions, see Authentication.

Create a subscription

When a customer subscribes to Meetch cancellation insurance in your system, you can transmit the subscription data to our API using one of the following methods:

• Send subscriptions individually (one request per subscription):
  

  Create a subscription

• Send multiple subscriptions in a single request (bulk method):
  

  Create subscriptions (Bulk)

Sample Payload :

{
  "order_reference": "123456",
  "currency": "EUR",
  "preferred_locale": "fr_FR",
  "insurance_amount": 14.49,
  "order_amount": 230,
  "order_date": "2025-01-01",
  "buyer_firstname": "John",
  "buyer_lastname": "Doe",
  "buyer_email": "johndoe@example.com",
  "items": [
    {
      "number": "000001",
      "label": "CARRE OR, BLOC B, SEAT 7",
      "price": 115,
      "event_name": "LES MISERABLES",
      "event_date_start": "2025-02-20T20:00:00+01:00",
      "event_date_end": "2025-02-20T20:00:00+01:00",
      "event_zipcode": "69006",
      "event_city": "LYON",
      "event_country": "FR",
      "event_place": "L’Amphithéâtre – Centre de congrès de Lyon - Cité"
    },
    {
      "number": "000002",
      "label": "CARRE OR, BLOC B, SEAT 8",
      "price": 115,
      "event_name": "LES MISERABLES",
      "event_date_start": "2026-02-20T20:00:00+01:00",
      "event_date_end": "2026-02-20T20:00:00+01:00",
      "event_zipcode": "69006",
      "event_city": "LYON",
      "event_country": "FR",
      "event_place": "L’Amphithéâtre – Centre de congrès de Lyon - Cité "
    }
  ]
}

Update a subscription

Update a subscription

Delete a subscription

Delete a subscription

This DELETE method should be used for extremely specific cases listed below:

• Error when booking
• Cancellation of the reservation in the days following the purchase
• Cancellation of the reservation where the distributor reimburses 100% of the amount paid by the customer

API: Going further

Prevent fraud

To help prevent potential fraud—such as issuing a refund to someone who has already attended the event—you can notify Meetch when a ticket has been scanned by using the following endpoint.

Notify item scan

When a ticket is flagged as scanned in our system, it will no longer be available for selection in the refund request form.

Additionally, our management team will be unable to process refunds for tickets that have been scanned, ensuring greater accuracy and security in refund handling.

Block a ticket

There are two methods available for retrieving data on refund requests processed by our team, which can help you take the necessary actions, such as canceling an order or tickets:

1. Using API:

Allows you to retrieve items refunded over a given period, every X amount of time.

List cancellations

2. Using our webhooks:

Type claim.refunded: To be informed in real time when a claim is validated by our teams. Webhooks are configured directly in the Operation > Connector manager.

Configure webhooks

Subscribe as an organization manager

You can manage subscriptions for your sub-organizations using a single API key.

To target a specific organization in your API requests, you must specify the organization_id using one of the following methods:

• In a POST request body by including the organization_id property.
• In a GET request query string by adding the organization_id parameter.
• Or, in the HTTP headers by setting the Organization header with the appropriate identifier.

Examples

1. JSON payload using a main API key with a child organization_id:

 {
  "foo": "bar",
  "organization_id": "org_child123"
}

2. Request using a main API key with the child organization_id in the HTTP header:

POST /v1/subscriptions HTTP/1.1
Host: api.ticketing.meetch.io
Authorization: Bearer MAIN_API_KEY
Content-Type: application/json
Organization: org_child123

{
  "foo": "bar"
}

Create subscription with an Event ID

You can include the event_id parameter when creating a subscription to associate the insured items with a specific event.

The event_id value may refer either to the event ID returned by the Meetch API (default behavior) or to your own external event ID, depending on how your integration is configured.

Example of body for /v1/subscriptions (POST) :

{
  "order_reference": "ABCDE",
  "currency": "EUR",
  "preferred_locale": "fr_FR",
  "order_amount": 380.0,
  "order_date": "2020-01-26",
  "items": [
    {
      "number": "123456789",
      "label": "Gold Ticket",
      "price": 380.0,
      "insurance_amount": 10.00,
      "event_id": "ev_XvoVpNxdl6Bx",
      "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"
    }
  ],
  "buyer_gender": "M",
  "buyer_firstname": "Alfred",
  "buyer_lastname": "Maison",
  "buyer_email": "example@upcover.fr",
  "buyer_date_of_birth": "1979-06-18"
}

A validation error is returned if the provided event_id does not match any existing event.

Deposit on a SFTP server of a CSV file

🔗 For File deposit instructions, see File deposit.

The uploaded file must have the following format:

📁 ticketing-exemple-import.csv

Column name	Required ? Y (Yes) N (Non)	Description
order_reference	Y	Order reference
order_date	Y	Order date Format: YYYY-MM-DD hh:mm:ss
currency	Y	Payment Currency (ISO 4217 3-Char) Example: EUR, USD
preferred_locale	Y	Example: fr_FR (French) or en_US (English). It is possible to specify only the language without the locale (fr or en)
insurance_amount	Y	Total amount of insurance including tax paid by the customer
order_amount	Y	Total cost of the order including TTC (ticket + insurance + options if applicable)
order_discount	N	Amount of the reduction applied by the distributor on the amount of the insurance premium. Default 0
buyer_firstname	Y	Customer's first name
buyer_lastname	Y	Customer’s last name
buyer_email	Y	Customer’s email
buyer_phone	N	Customer’s phone number
buyer_address	N	Customer’s address
buyer_country	N	Customer’s city
buyer_date_of_birth	N	Customer's date of birth (YYYY-MM-DD)
item_number	Y	Ticket number / Barcode
item_label	Y	Ticket name
item_price	Y	Ticket price
item_insurance_amount	Y	Ticket insurance amount
item_holder_name	Y	Name of the customer attached to the ticket
quantity	N	Default 1
event_name	Y	Event name
event_date_start	Y	Event start date Expected format: YYYY-MM-DD or specifying the time if applicable (YYYY-MM-DD hh:mm)
event_date_end	Y	End date of the event Expected format: YYYY-MM-DD or specifying the time if applicable (YYYY-MM-DD hh:mm)
event_address	N	Event address
event_zipcode	N	Postal code of the event
event_city	N	Event city
event_place	N	Location of the event (useful to specify, for example, the name of a performance hall)
event_type	Y	Type of event. Possible value: show, festival
status	N	Indicates whether we are on a subscription creation or update. Possible values: C (create, default value), U (update), A (cancel). In the case of a cancellation on a single item, you can use the “item_cancel” status.

Any other information deemed useful may be transmitted in additional columns.