From the legacy Booking API to the new Partner API

This guide provides instructions for migrating your integration from the legacy Booking API to the new, more robust Partner API.

The Partner API is a new component of our next-generation platform, P5. This platform-wide upgrade introduces significant improvements in security, performance, and data architecture. The key migration changes you need to be aware of are:

1. Authentication: Moving from Basic Authentication to the more secure OAuth 2.0 Client Credentials flow.
2. API Structure: Shifting from a single, multi-purpose endpoint (/api/v1/booking) to a modern, resource-oriented RESTful design.
3. Voucher Identifiers: Shifting from a numeric to a new 8-character alphanumeric referenceNumber.
4. Batch Operations: The legacy API supported batch operations (updating multiple vouchers in one call). The new API operates on a single voucher certificate per request, which provides clearer, more atomic transactions.

Important

The legacy Booking API will be deprecated. Please migrate your applications to the new Partner API to ensure continued service and access to new features.

---

1. Authentication

The most significant change is the authentication mechanism. The legacy API used HTTP Basic Authentication, while the new Partner API uses OAuth 2.0.

Before: Basic Authentication

Previously, you would include your username and password, Base64-encoded, in the Authorization header with every API call.

GET /api/v1/booking?orderItemIds=12345 HTTP/1.1
Host: api.skchase.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

After: OAuth 2.0 Client Credentials Flow

The new API uses OAuth 2.0 for enhanced security. Instead of sending credentials with every request, you will exchange your client_id and client_secret for a temporary bearer token. See the Authentication page for more details.

---

2. Identifier Migration: From orderItemId to referenceNumber

The introduction of the new Partner API is part of our platform evolution to P5. A core part of the P5 refactor was redesigning how vouchers are identified to be more robust and secure.

Voucher Mapping

You do not need to do anything to map your existing vouchers to the new format. The mapping between circulating vouchers with legacy references and the new P5 format is done automatically by the platform when the vouchers for your venues are migrated.

The Old System: Numeric orderItemId

In the legacy system, vouchers had a composite reference number (e.g., 76921-2765527-3639452). Your integration used the final numeric part (3639452) as the unique orderItemId in API requests.

The New System: Alphanumeric referenceNumber

In the new Partner API, all vouchers are assigned a new, 8-character alphanumeric code (e.g., GLTJJK9N). This is the primary certificateReferenceNumber.

Legacy Number Support and Transitioning

To ensure a smooth migration, the new Partner API fully supports the old numeric orderItemIds.

You can use a legacy orderItemId directly in the new API endpoints. When you do, the API response will provide you with the new alphanumeric certificateReferenceNumber as well.

Example: Querying with a Legacy ID

Make a GET request using the old orderItemId:

GET /api/v1/voucher-certificates/3639452 HTTP/1.1
Host: papi.skchase.com
Authorization: Bearer ...

Response: Mapping Old to New

The response body will contain both the new primary reference and the old legacy reference you queried with.

{
  // ... other voucher details
  "certificateReferenceNumber": "GLTJJK9N", // The new, primary alphanumeric reference
  "externalReferenceNumber": "3639452" // The legacy numeric ID you used
  // ... other voucher details
}

---

3. Endpoint and Operation Migration

The legacy API used a single URL (/api/v1/booking) for all operations, distinguishing them by the HTTP method. The new API uses distinct, resource-focused URLs.

Operation: Check Voucher Status

Aspect	Legacy Booking API	New Partner API
HTTP Method	GET	GET
Endpoint	/api/v1/booking	/api/v1/voucher-certificates/{referenceNumber}
Identifier	orderItemId passed in query string	referenceNumber passed in URL path
Batch Support	Yes (?orderItemIds=1,2,3)	No (One call per voucher)

Before (Legacy)

A GET request to the /booking endpoint with a comma-separated list of IDs.

GET /api/v1/booking?orderItemIds=12345,67890 HTTP/1.1
Host: api.skchase.com
Accept: application/json
Authorization: Basic ...

After (New Partner API)

A separate GET request is now required for each voucher using its referenceNumber.

GET /api/v1/voucher-certificates/AAAA1111 HTTP/1.1
Host: papi.skchase.com.com
Authorization: Bearer ...

GET /api/v1/voucher-certificates/BBBB2222 HTTP/1.1
Host: papi.skchase.com.com
Authorization: Bearer ...

The new response (VoucherCertificateApiModel) is significantly more detailed, providing full product details, balance information, and a structured bookingInfo object.

Operation: Set Voucher Booked

Aspect	Legacy Booking API	New Partner API
HTTP Method	PUT	POST
Endpoint	/api/v1/booking	/api/v1/voucher-certificates/{referenceNumber}/booking
Identifier	orderItemId in request body	referenceNumber in URL path
Request Body	Array of {orderItemId, notes}	Single object {notes, bookingDate, bookingTime, bookingReference}
Batch Support	Yes	No (One call per booking)

Before (Legacy)

A PUT request with a JSON array of items to book.

PUT /api/v1/booking HTTP/1.1
Host: api.skchase.com
Content-Type: application/json
Authorization: Basic ...

[
    {
        "orderItemId": 12345,
        "notes": "Celebrating an anniversary."
    }
]

After (New Partner API)

A POST request to the voucher's specific /booking endpoint. The new API requires separate fields for date and time and uses POST to signify the creation of a new booking resource.

POST /api/v1/voucher-certificates/AAAA1111/booking HTTP/1.1
Host: papi.skchase.com.com
Content-Type: application/json
Authorization: Bearer ...

{
  "notes": "Celebrating an anniversary.",
  "bookingDate": "2025-08-01",
  "bookingTime": "19:30:00",
  "bookingReference": "CONF-XY-778899"
}

Operation: Remove Voucher Booking

Aspect	Legacy Booking API	New Partner API
HTTP Method	DELETE	DELETE
Endpoint	/api/v1/booking	/api/v1/voucher-certificates/{referenceNumber}/booking
Identifier	orderItemId in request body	referenceNumber in URL path
Request Body	Yes (Array of {orderItemId, notes})	No Body Required
Batch Support	Yes	No (One call per cancellation)

Before (Legacy)

A DELETE request with a JSON body specifying which bookings to remove.

DELETE /api/v1/booking HTTP/1.1
Host: api.skchase.com
Content-Type: application/json
Authorization: Basic ...

[
    {
        "orderItemId": 12345,
        "notes": "Cancelled by customer."
    }
]

After (New Partner API)

A DELETE request to the voucher's specific /booking endpoint. The identifier is now in the URL, and a request body is no longer necessary, which is more aligned with REST principles.

DELETE /api/v1/voucher-certificates/AAAA1111/booking HTTP/1.1
Host: papi.skchase.com.com
Authorization: Bearer ...

---

4. Error Handling

The new Partner API uses standardized ProblemDetails (RFC 7807) for error responses. This provides more consistent and machine-readable error information.

Example 409 Conflict Response

If you attempt to book a voucher that is already booked:

{
  "type": "urn:skchase:error:ItemAlreadyBooked",
  "title": "ItemAlreadyBooked",
  "status": 409,
  "detail": "The item is already booked",
  "traceId": "0HNDQ3PRFUJPN:00000027"
}

This structured approach makes it easier to handle errors programmatically.