Guides
  1. Workflows

Marketplace Checkout Integration

👍

Scopes required: ProductAvailability_Get, Product_Get, BookingDraft_Create, BookingDraft_Costs, BookingDraft_Publish, Payment_Create

This recipe walks through selling a venue's tickets on your marketplace, from token to confirmed booking. Use the Playground environment (https://api.play.roller.app) while developing.

1. Authenticate

curl -X POST https://api.roller.app/token \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" }'
{ "access_token": "eyJhbGciOi...", "expires_in": 86400, "token_type": "Bearer" }

Cache the token — it's valid for up to 24 hours, and the token endpoint is limited to 60 requests/minute.

2. Check availability

curl "https://api.roller.app/product-availability?date=2026-07-01" \
  -H "Authorization: Bearer $TOKEN"

The response lists products with capacity and session times for the date. Surface these to your guest as purchasable inventory.

3. Create a draft booking

A draft holds the items while the guest completes checkout on your marketplace:

curl -X POST https://api.roller.app/bookings/draft \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketplace order #48211",
    "customer": { "firstName": "Jane", "lastName": "Doe", "email": "[email protected]" },
    "items": [ { "productId": 123456, "quantity": 2, "bookingDate": "2026-07-01", "startTime": "10:00" } ]
  }'

4. Confirm costs

Always price from ROLLER, never from your own cache — fees, taxes and pricing rules are venue-controlled:

curl -X POST https://api.roller.app/bookings/draft/costs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uniqueId": "DRAFT_BOOKING_ID" }'

5. Publish the booking

Once the guest pays on your marketplace, publish the draft to confirm it:

curl -X POST https://api.roller.app/bookings/draft/publish \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uniqueId": "DRAFT_BOOKING_ID" }'

6. Record the payment

curl -X POST https://api.roller.app/bookings/BOOKING_UNIQUE_ID/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 55.50, "paymentMethod": "ThirdParty" }'

7. Handle failure paths

  • Draft expired or capacity gone at publish → 409 Conflict with validation errors: re-check availability and re-draft.
  • Guest abandons checkout → no action needed; unpublished drafts lapse.
  • Guest cancels later → POST /bookings/{uniqueId}/cancel (scope Booking_Cancel), then manage refunds.
📘

For full request/response models see the checkout workflow guide and the API Reference.

Updated 23 days ago

Did this page help you?