POSTBookings

Create Booking

/api/v1/bookings/create

Create one or more bookings in a single request. Each item in the items array maps to one product/resource booking. All items share the same customer and top-level metadata, while the response returns grouped booking items with linked resource details.

Authentication Required

Include Bearer token in Authorization header: Authorization: Bearer YOUR_TOKEN

Request Body Fields

Field	Type	Required	Description
`partnerId`	`integer`	Yes	Partner ID.
`items`	`array`	Yes	One or more booking items.
`items[].productCode`	`string`	Yes	Product/tour code to book
`items[].reservationDateTime`	`string`	Yes	Reservation date or datetime (ISO 8601, e.g. 2026-03-25 or 2026-03-25T10:00:00)
`items[].quantities`	`array`	Yes	Quantity lines for the item — must contain at least one entry
`items[].quantities[].label`	`string`	Yes	Quantity line label (e.g., adult, child, senior)
`items[].quantities[].quantity`	`number`	Yes	Number of units for this line (must be > 0)
`items[].quantities[].price`	`number`	Yes	Unit price for this quantity line (>= 0)
`customer`	`object`	Yes	Customer details shared across all items
`customer.firstName`	`string`	Yes	Customer first name
`customer.lastName`	`string`	No	Customer last name
`customer.title`	`string`	No	Customer title (Mr, Mrs, Ms, etc.)
`customer.email`	`string`	No	Customer email address
`customer.phone`	`string`	No	Customer phone number
`customer.address`	`string`	No	Customer street address
`customer.city`	`string`	No	Customer city
`customer.country`	`string`	No	Customer country code or name
`customer.postCode`	`string`	No	Customer postal / ZIP code
`customerNote`	`string`	No	Customer note for booking
`resellerReference`	`string`	No	Reseller booking reference
`resellerSource`	`string`	No	Reseller source / channel
`resellerNote`	`string`	No	Reseller note for booking
`guests`	`array`	No	Guest list applied to booking
`guests[].title`	`string`	No	Guest title
`guests[].firstName`	`string`	No	Guest first name
`guests[].lastName`	`string`	No	Guest last name
`guests[].age`	`number`	No	Guest age
`payments`	`array`	No	Payment records applied to booking
`payments[].method`	`string`	Yes	Payment method (e.g., CREDIT_CARD, VOUCHER)
`payments[].amount`	`number`	Yes	Payment amount (>= 0)
`payments[].reference`	`string`	Yes	Gateway or provider payment reference

Request Body Example

Example:

{
  "partnerId": 42,
  "items": [
    {
      "productCode": "TOUR-EIFFEL-SKIP-LINE",
      "reservationDateTime": "2026-03-25T10:00:00",
      "quantities": [
        {
          "label": "adult",
          "quantity": 2,
          "price": 75
        },
        {
          "label": "child",
          "quantity": 1,
          "price": 40
        }
      ]
    }
  ],
  "customer": {
    "title": "Mr",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+33612345678",
    "address": "15 Avenue de l Opera",
    "city": "Paris",
    "country": "FR",
    "postCode": "75001"
  },
  "customerNote": "Wheelchair accessible entrance requested",
  "resellerReference": "RS-TRAVELMATE-9912",
  "resellerSource": "mytravelmate",
  "resellerNote": "VIP customer, prioritize fast check-in",
  "guests": [
    {
      "title": "Mr",
      "firstName": "John",
      "lastName": "Doe",
      "age": 37
    },
    {
      "title": "Mrs",
      "firstName": "Jane",
      "lastName": "Doe",
      "age": 35
    }
  ],
  "payments": [
    {
      "method": "CREDIT_CARD",
      "amount": 190,
      "reference": "txn-2026-03-20-001"
    },
    {
      "method": "VOUCHER",
      "amount": 40,
      "reference": "voucher-ABCD-2026"
    }
  ]
}

Response

Success Response Example:

{
  "success": true,
  "booking": {
    "bookingNumber": "PC2185IEC",
    "items": [
      {
        "productCode": "TOUR-EIFFEL-SKIP-LINE",
        "reservationDate": "2026-03-25",
        "reservationTime": "10:00",
        "quantities": [
          {
            "label": "adult",
            "quantity": 2,
            "price": 75
          },
          {
            "label": "child",
            "quantity": 1,
            "price": 40
          }
        ],
        "resource": {
          "code": "RES-EIFFEL-1000",
          "name": "Eiffel Tower 10AM Entry",
          "type": "ticket"
        }
      }
    ],
    "guests": [
      {
        "title": "Mr",
        "firstName": "John",
        "lastName": "Doe",
        "age": 37
      },
      {
        "title": "Mrs",
        "firstName": "Jane",
        "lastName": "Doe",
        "age": 35
      }
    ],
    "payments": [
      {
        "method": "CREDIT_CARD",
        "amount": 190,
        "currency": "EUR",
        "reference": "txn-2026-03-20-001"
      },
      {
        "method": "VOUCHER",
        "amount": 40,
        "currency": "EUR",
        "reference": "voucher-ABCD-2026"
      }
    ],
    "customerNote": "Wheelchair accessible entrance requested",
    "resellerReference": "RS-TRAVELMATE-9912",
    "resellerSource": "mytravelmate",
    "resellerNote": "VIP customer, prioritize fast check-in",
    "status": "created",
    "customer": {
      "title": "Mr",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+33612345678",
      "email": "[email protected]"
    }
  }
}

Error Response

Error Example:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed"
  }
}

Available Errors

HTTP Status	Code	Meaning
`401`	`UNAUTHORIZED`	Invalid or missing authentication token
`422`	`VALIDATION_ERROR`	Request payload validation failed
`400`	`INVALID_REQUEST`	Missing/invalid payload fields: partnerId, items, items[].productCode, items[].reservationDateTime, items[].quantities, or customer.firstName
`403`	`FORBIDDEN`	Partner and Product do not match
`404`	`NOT_FOUND`	Product not found
`409`	`CONFLICT`	Resource not available for requested slot
`500`	`INTERNAL_SERVER_ERROR`	Server error

← Back to Home