> For the complete documentation index, see [llms.txt](https://syticks.gitbook.io/merpi-by-syticks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://syticks.gitbook.io/merpi-by-syticks/api-reference/bus-ticketing-routes-terminals-schedules-buses-purchase-etc/buy-bus-ticket-endpoint-deprecated-v1.md). # Buy Bus Ticket Endpoint (DEPRECATED - V1) ### **Overview** This endpoint handles transport ticket purchase for **Timed Schedules only**. When your customers call this endpoint through your platform, transport tickets for their selected route (Lagos→Abuja, etc.) are created and sent to their email. You can track all purchases from your MERPI dashboard. #### **Important Notes** * **Timed Schedules Only**: This endpoint only works with routes that have fixed departure times * **Random Schedules Not Supported**: For Random Schedule routes (flexible timing), you must use the V2 endpoint * **Email Delivery**: Providing the correct customer email is critical because tickets are delivered by mail. Wrong email = tickets go to the wrong person * **Seat Selection Required**: You must provide specific seat IDs from the schedule response ### **Migrating to V2** The **V2 endpoint** supports both Timed and Random schedules with a unified interface. Key differences: | Feature | V1 (This Endpoint) | V2(New Endpoint) | | ----------------------- | ---------------------- | ------------------------- | | Schedule Support | Timed only | Both Timed and Random | | Required Fields | `schedule_id`, `seats` | Varies by `schedule_type` | | Random Schedule Support | ❌ Not supported | ✅ Fully supported | 📘 **See V2 Documentation:** [Link to V2 endpoint documentation](/merpi-by-syticks/api-reference/bus-ticketing-routes-terminals-schedules-buses-purchase-etc/buy-bus-ticket-endpoint-v2.md) ### **API Reference** #### **Endpoint** ``` POST /api/v1/merpi/transport/buy/tickets ``` ### Request Body Parameters
ParameterTypeRequiredDescription
schedule_idIntegerYesUnique identifier for the bus schedule being booked (from Get Schedules endpoint)
seatsArray[Integer]YesList of seat IDs being booked (e.g., [9, 4, 3] indicates seats with ID 9, 4, and 3)
departure_dateStringYesDate and time of departure in format: YYYY-MM-DD HH:MM (e.g., "2024-07-23 20:21")
customer_infoObjectYesCustomer information object
customer_info.nameStringNoFull name of the customer
customer_info.emailStringYesEmail address (tickets will be sent here)
customer_info.phone_numberStringYesCustomer's phone number
customer_info.dobStringNoDate of birth in format: DD/MM/YYYY
customer_info.usernameStringNoUsername for the customer
customer_info.kinObjectNoNext of kin information
customer_info.kin.first_nameStringNoFirst name of next of kin
customer_info.kin.last_nameStringNoLast name of next of kin
customer_info.kin.phone_numberStringNoPhone number of next of kin
customer_info.kin.emailStringNoEmail of next of kin
customer_info.kin.genderStringNoGender of next of kin (e.g., "male", "female")
customer_info.kin.relationshipStringNoRelationship to customer (e.g., "son", "daughter", "spouse")
### Response Fields | Field | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------- | | `success` | Boolean | Indicates if the request was successful | | `status` | Integer | HTTP status code (201 for successful creation) | | `message` | String | Human-readable message about the result | | `data.reference` | String | Unique transaction reference (e.g., "TR197016656") | | `data.invoice_id` | Integer | Invoice ID for the purchase(Customer can present this at the transport terminal) | | `data.name` | String | Customer's name | | `data.email` | String | Customer's email (where ticket was sent) | | `data.phone_number` | String | Customer's phone number | | `data.departure_date` | String | Confirmed departure date and time | | `data.seat` | Array | Array of booked seat objects with details | | `data.seat[].id` | Integer | Seat ID | | `data.seat[].name` | String | Seat name/position (e.g., "1-1" for row 1, column 1) | | `data.seat[].row` | Integer | Row number | | `data.seat[].column` | Integer | Column number | | `data.bus` | Object | Complete bus information | | `data.bus.seat_grid` | Array | 2D array showing all seats and their availability | | `data.schedule` | Object | Schedule information for the booked trip | ## Buy Bus Tickets > Endpoint to purchase bus tickets for a specific schedule and seats. ```json {"openapi":"3.0.3","info":{"title":"Syticks API","version":"1.0.0"},"paths":{"/api/v1/merpi/transport/buy/tickets":{"post":{"summary":"Buy Bus Tickets","description":"Endpoint to purchase bus tickets for a specific schedule and seats.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["schedule_id","seats","departure_date","customer_info"],"properties":{"schedule_id":{"type":"integer","description":"Unique identifier for the bus schedule being booked."},"seats":{"type":"array","items":{"type":"integer"},"description":"List of seat ID’s being booked (e.g., [9, 4, 3] indicates seats with ID 9, 4, and 3)."},"departure_date":{"type":"string","format":"date-time","description":"Date and time of the bus departure in YYYY-MM-DD HH:MM format (e.g., \"2024-07-23 20:21\")."},"customer_info":{"type":"object","required":["email","kin"],"properties":{"name":{"type":"string","description":"Customer's full name (e.g., \"Victor Ebuka\")."},"email":{"type":"string","format":"email","description":"Customer's primary email address (e.g., \"victor@gmail.com\")."},"phone_number":{"type":"string","description":"Customer's phone number (e.g., \"08085825362\")."},"dob":{"type":"string","format":"date","description":"Customer's date of birth in MM/DD/YYYY format (e.g., \"01/12/2000\")."},"username":{"type":"string","description":"Customer's username for the booking system (e.g., \"victor_ebuka\")."},"kin":{"type":"object","required":["phone_number","email"],"properties":{"first_name":{"type":"string","description":"Emergency contact's first name (e.g., \"Richard\")."},"last_name":{"type":"string","description":"Emergency contact's last name (e.g., \"Raymond\")."},"phone_number":{"type":"string","description":"Emergency contact's phone number (e.g., \"08085825362\")."},"email":{"type":"string","format":"email","description":"Emergency contact's email address (e.g., \"phav@yopmail.com\")."},"gender":{"type":"string","description":"Emergency contact's gender (e.g., \"male\")."},"relationship":{"type":"string","description":"Relationship of the emergency contact to the customer (e.g., \"son\")."}}}}}}}}}},"responses":{"200":{"description":"Successful purchase of bus tickets.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"reference":{"type":"string"},"invoice_id":{"type":"integer"},"name":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"departure_date":{"type":"string","format":"date-time"},"seat":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"row":{"type":"integer"},"column":{"type":"integer"}}}},"bus":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"image":{"type":"string"},"seats":{"type":"integer"},"price":{"type":"string"},"rows":{"type":"integer"},"columns":{"type":"integer"},"seat_grid":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"seat":{"type":"boolean"},"row":{"type":"integer"},"column":{"type":"integer"}}}}}}},"schedule":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"image":{"type":"string"},"seats":{"type":"integer"},"price":{"type":"string"}}}}}}}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}} ``` ### **Key Differences from V2** #### **What V1 Does Not Support (Use V2 Instead):** 1. **Random Schedules**: Cannot purchase tickets for routes with flexible timing. 2. **No Seat Selection for Random Routes**: V2 handles seat assignment automatically for Random schedules as random schedules don't need seat selection. 3. **Different Request Structure**: V2 has dynamic request structure based on `schedule_type` . #### **V1 vs V2 Request Comparison** **V1 (Timed Only):** ```json { "schedule_id": 5, "seats": [9, 4, 3], "departure_date": "2024-07-23 20:21", "customer_info": { ... } } ``` **V2 (Random Schedule):** ```json { "schedule_type": "random", "bus_id": 9, "route_id": 28, "no_of_passengers": 1, "departure_date": "2025-12-09", "departure_time": "23:50", "customer_info": { ... } } ``` **V2 (Timed Schedule):** ```json { "schedule_type": "timed", "schedule_id": 5, "seats": [9, 4, 3], "departure_date": "2024-07-23 20:21", "customer_info": { ... } } ``` ### **Important Implementation Notes** #### **For Timed Schedules (This Endpoint)** 1. **Get Available Seats First**: Call the Get Schedules endpoint to retrieve available seats 2. **Show Seat Selection UI**: Display the seat grid to customers and let them choose specific seats(If you don't pass seats, we'll automatically assign random seat(s) from the available ones in the bus) 3. **Send Seat IDs**: Include the selected seat IDs in the `seats` array 4. **Fixed Departure Time**: The departure time is predetermined by the schedule #### **Why You Need to Migrate to V2** * **Unified Interface**: Handle both Timed and Random schedules with one endpoint * **Better Support**: Future updates and improvements will focus on V2 * **Complete Coverage**: Access all route types in the system and more routes generally. * **Flexibility**: Adapt to different schedule types dynamically ### **Common Use Cases** #### **Timed Schedule Example: Lagos to Abuja** * Customer selects a long-distance route with fixed 6 AM departure * System shows available seats using seat grid * Customer chooses seats 9, 4, and 3 * Ticket is purchased with exact seats and fixed departure time * Customer receives ticket via email with seat assignments