RightRock API

Show your cinema's films, showtimes, prices and seats on your own website or app, and sell tickets that go straight into RightRock: same seats, same reports, same door check.

Getting started

  1. In RightRock, open Developers and create a secret key. You see it once, so store it safely.
  2. To sell tickets, turn on Sell tickets online in Cinema settings.
  3. Call the API from your server, sending the key in the Authorization header. Never put the key in browser code or a mobile app.
curl https://app.rightrock.co/api/v1/screenings?from=2026-11-07 \
  -H "Authorization: Bearer rr_your_secret_key"
  • Money is an integer in the currency's smallest unit: 500000 is ₦5,000.00.
  • Times are ISO 8601 in UTC. Use the cinema's time_zone to show local times.
  • Errors look like { "error": { "code": "…", "message": "…" } }, with a matching HTTP status.
  • Each key can make 300 requests a minute.
  • Only on-sale screenings are visible; drafts and cancelled showings never appear.

Selling tickets

  1. List showtimes with GET /api/v1/screenings.
  2. When a customer picks one, get its prices and seat plan with GET /api/v1/screenings/{id}.
  3. Create the order with POST /api/v1/orders. The seats are held for 10 minutes.
  4. Redirect the customer to checkout_url. After paying they return to your return_url.
  5. Confirm with GET /api/v1/orders/{id}: status paid means the tickets are valid. RightRock also emails them to the customer.

Rather not build a booking flow? Link to your RightRock booking page instead: https://app.rightrock.co/c/your-handle.

Reference

GET /api/v1/cinema

Your cinema

Name, currency, time zone, whether online sales are on, and open locations.

Response

{ "data": { "name": "Silverbird Cinemas", "handle": "silverbird", "currency": "NGN", "time_zone": "Africa/Lagos", "live": true, "online_sales": true,
  "locations": [{ "id": "loc_…", "name": "Ikeja", "city": "Lagos", "address": "…", "phone": "…" }] } }

GET /api/v1/films

Films

Films showing now or coming soon.

statusnow_showing or coming_soon

Response

{ "data": [{ "id": "flm_…", "title": "…", "runtime_minutes": 112, "rating": "12A", "poster_url": "https://…", "status": "now_showing" }] }

GET /api/v1/screenings

Showtimes

On-sale screenings between two dates in the cinema's time zone, with seats left. Up to 31 days; defaults to the next 7.

fromFirst date, like 2026-11-07
toLast date, inclusive
film_idOnly this film
location_idOnly this location

Response

{ "data": [{ "id": "scn_…", "film_id": "flm_…", "film_title": "…", "starts_at": "2026-11-07T17:00:00.000Z", "film_starts_at": "…", "ends_at": "…",
  "format": "2D", "location": { "id": "loc_…", "name": "Ikeja" }, "screen": { "id": "scr_…", "name": "Screen 1", "features": [] },
  "seating": "assigned", "capacity": 120, "available": 87 }] }

GET /api/v1/screenings/{id}

One showtime, with prices and seats

Ticket types and prices (by seat category), and for assigned seating the seat plan with each seat's status. Starts_at is when doors open.

Response

{ "data": { "id": "scn_…", "status": "on_sale", "currency": "NGN",
  "ticket_types": [{ "id": "tt_…", "name": "Adult", "prices": { "standard": 500000, "premium": 750000 } }],
  "seats": [{ "row": "A", "cells": [{ "type": "seat", "id": "A1", "category": "standard", "status": "available" }, { "type": "gap" }] }] } }

POST /api/v1/orders

Book tickets

Holds the seats for 10 minutes and starts a payment. Send the customer to checkout_url. After paying they come back to return_url, the order becomes paid and the e-tickets are emailed to them. Seats someone else took return 409 with the seat ids.

Request body

{ "screening_id": "scn_…",
  "tickets": [{ "ticket_type_id": "tt_…", "seat_id": "F7" }, { "ticket_type_id": "tt_…", "seat_id": "F8" }],
  "customer": { "name": "Ada Okafor", "email": "ada@example.com", "phone": "+2348031234567" },
  "promo_code": "STUDENT10",
  "return_url": "https://your-site.com/booking/done" }

Response

{ "data": { "id": "ord_…", "reference": "R7K3M9Q", "status": "pending", "total": 1000000, "currency": "NGN",
  "expires_at": "…", "checkout_url": "https://…", "tickets": [{ "seat_id": "F7", "status": "held", "code": null }] } }

GET /api/v1/orders/{id}

Check an order

Status is pending, paid, expired, refund_due, partially_refunded or refunded. Ticket codes appear once paid.

Response

{ "data": { "id": "ord_…", "status": "paid", "tickets": [{ "seat_id": "F7", "type": "Adult", "status": "valid", "code": "TQ4W-8XKM-2N" }] } }

Questions? Contact RightRock support from your workspace. Sign in