Reservation APIs
The Reservation API handles the temporary allocation of available slots. A reservation locks a slot for a defined window (e.g., 5 minutes), allowing the user to confirm or release it later. This prevents overbooking and ensures concurrency safety across multiple users or systems.
Base URL
https://sandbox-apis.prayog.io/slotsAPI Response Status Codes
| Code | Description |
|---|---|
| 1000 | OK |
| 1001 | Success |
| 1002 | Partial Success |
| 4000 | Bad Request |
| 4004 | Not Found |
| 5000 | Internal Server Error |
HTTP Response Status Codes
| Code | Description |
|---|---|
| 200 | OK |
| 201 | Created |
| 207 | Multi Status |
| 400 | Bad Request |
| 404 | Not Found |
| 500 | Internal Server Error |
Available Endpoints
- Find Slots Availability
- Reserve Slot
- Reserve Slots
- Confirm Slot
- Confirm Slots
- Release Slot
- Release Slots
- Cancel Slot
- Cancel Slots
1. Find Slots Availability
To check the slots availability.
Method: POST
Endpoint: /api/v1/slots/availability
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Request Query Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| page | int number | No | Page | 1 |
| limit | int number | No | Page limit | 10 |
Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| type | string | Yes | Slot type (‘pickup’, ‘delivery’) | "pickup" |
| pincode | string | Yes | location pincode | "560001" |
| shipments | array | Yes | List of shipment objects | [{...}] |
Shipments Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| dimensions | object | Yes | Dimensions object | {...} |
| capacity | object | Yes | Capacity object | {...} |
Dimensions Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| length | number | Yes | Length in ‘cm’ | 10 |
| width | number | Yes | Width in ‘cm’ | 10 |
| height | number | Yes | Height in ‘cm’ | 10 |
Capacity Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| volumetricWeight | number | Yes | Volumetric weight in ‘kg’ | 4 |
| physicalWeight | number | Yes | Physical weight in ‘kg’ | 3 |
Sample Request Body
{ "type": "pickup", "pincode": "560001", "shipments": [ { "dimensions": { "length": 10, "width": 10, "height": 10 }, "capacity": { "volumetricWeight": 4, "physicalWeight": 3 } }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 } }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 } } ]}Sample Success Response
{ "status": "success", "message": "Slot availability fetched successfully.", "data": { "type": "pickup", "pincode": "560001", "shipments": [ { "dimensions": { "length": 10, "width": 10, "height": 10 }, "capacity": { "volumetricWeight": 4, "physicalWeight": 3 }, "availableSlots": [ { "date": "2025-05-11", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-12", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-13", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-14", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-15", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-16", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-17", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-18", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-19", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-20", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 10, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] } ] }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "availableSlots": [ { "date": "2025-05-11", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-12", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-13", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-14", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-15", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-16", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-17", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-18", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-19", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-20", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 10, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] } ] }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "availableSlots": [ { "date": "2025-05-11", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-12", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-13", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-14", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-15", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-16", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-17", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-18", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-19", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 125, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] }, { "date": "2025-05-20", "timings": [ { "slotId": 122, "from": "03:00", "to": "04:00" }, { "slotId": 10, "from": "06:00", "to": "07:00" }, { "slotId": 1, "from": "09:00", "to": "10:00" }, { "slotId": 137, "from": "16:00", "to": "17:00" } ] } ] } ] }, "pagination": { "page": 1, "limit": 10, "offset": 0, "totalPage": 4, "totalItem": 40 }, "statusCode": 1000}Sample Error Response
{ "status": "error", "error": "Property page must be at least 1. Property page must be an integer.", "statusCode": 4000}Sample No Match Response
{ "status": "success", "message": "Slot availability fetched successfully", "data": { "type": "pickup", "pincode": "560601", "shipments": [ { "dimensions": { "length": 10, "width": 10, "height": 10 }, "capacity": { "volumetricWeight": 4, "physicalWeight": 3 }, "availableSlots": [] }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "availableSlots": [] }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "availableSlots": [] } ] }, "pagination": { "page": 1, "limit": 10, "offset": 0, "totalPage": 4, "totalItem": 40 }, "statusCode": 1000}2. Reserve Slot
To reserve the slot.
Method: POST
Endpoint: /api/v1/slot/reserve
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| slotId | number | Yes | Slot ID | 1 |
| date | string | No | Slot date (YYYY-MM-DD) | 2025-05-20 |
| dimensions | object | Yes | Dimensions object | {...} |
| capacity | object | Yes | Capacity object | {...} |
Dimensions Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| length | number | Yes | Length in ‘cm’ | 1 |
| width | number | Yes | Width in ‘cm’ | 1 |
| height | number | Yes | Height in ‘cm’ | 1 |
Capacity Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| volumetricWeight | number | Yes | Volumetric weight in ‘kg’ | 1 |
| physicalWeight | number | Yes | Physical weight in ‘kg’ | 1 |
Sample Error Response
{ "slotId": 1, "date": "2025-05-20", "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }}Sample Success Response
{ "status": "success", "message": "Slot reserved successfully.", "data": { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-05-20", "reservationId": 149, "reservedAt": "2025-05-19T08:32:17.750Z", "expiresAt": "2025-05-19T08:37:17.750Z" }, "statusCode": 1000}Sample Error Response
{ "status": "error", "error": "Requested slot not found.", "statusCode": 4004}3. Reserve Slots
To reserve the slots.
Method: POST
Endpoint: /api/v1/slots/reserve
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Array Of Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| slotId | number | Yes | Slot ID | 1 |
| date | string | No | Slot date (YYYY-MM-DD) | 2025-05-27 |
| dimensions | object | Yes | Dimensions object | {...} |
| capacity | object | Yes | Capacity object | {...} |
Dimensions Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| length | number | Yes | Length in ‘cm’ | 1 |
| width | number | Yes | Width in ‘cm’ | 1 |
| height | number | Yes | Height in ‘cm’ | 1 |
Capacity Object
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| volumetricWeight | number | Yes | Volumetric weight in ‘kg’ | 1 |
| physicalWeight | number | Yes | Physical weight in ‘kg’ | 1 |
Sample Error Response
[ { "slotId": 1, "date": "2025-05-27", "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 } }, { "slotId": 1, "date": "2025-075-27", "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 } }]Sample All Success Response
{ "status": "success", "message": "All slots reserved successfully.", "data": [ { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-05-27", "reservationId": 152, "reservedAt": "2025-05-19T09:26:13.639Z", "expiresAt": "2025-05-19T09:31:13.639Z" }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-05-27", "reservationId": 153, "reservedAt": "2025-05-19T09:26:15.976Z", "expiresAt": "2025-05-19T09:31:15.976Z" } ], "statusCode": 1001}Sample Partial Success Response
{ "status": "partial_success", "message": "Some slots reserved successfully.", "data": [ { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-05-27", "reservationId": 150, "reservedAt": "2025-05-19T09:25:29.271Z", "expiresAt": "2025-05-19T09:30:29.271Z" }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-075-27", "error": "Date must be a valid ISO 8601 date string." } ], "statusCode": 1002}Sample All Error Response
{ "status": "error", "message": "No slots reserved successfully.", "data": [ { "dimensions": { "length": 1, "width": 15656565, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 1, "date": "2025-05-27", "error": "Requested slot booked." }, { "dimensions": { "length": 1, "width": 1, "height": 1 }, "capacity": { "volumetricWeight": 1, "physicalWeight": 1 }, "slotId": 16767, "date": "2025-05-27", "error": "Requested slot not found." } ], "statusCode": 4000}4. Confirm Slot
To confirm the slot.
Method: POST
Endpoint: /api/v1/slot/confirm
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 147 |
Sample Error Response
{ "reservationId": 147}Sample Success Response
{ "status": "success", "message": "Slot confirmed successfully", "data": { "reservationId": 147, "confirmedAt": "2025-05-16T06:54:01.619Z" }, "statusCode": 1000}Sample Error Response
{ "status": "error", "error": "Reservation expired.", "statusCode": 4004}5. Confirm Slots
To confirm the slots.
Method: POST
Endpoint: /api/v1/slots/confirm
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Array Of Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 95 |
Sample Error Response
[ { "reservationId": 95 }, { "reservationId": 96 }]Sample All Success Response
{ "status": "success", "message": "All slots confirmed successfully.", "data": [ { "reservationId": 95, "confirmedAt": "2025-05-11T17:20:04.481Z" }, { "reservationId": 96, "confirmedAt": "2025-05-11T17:20:04.486Z" } ], "statusCode": 1001}Sample Partial Success Response
{ "status": "partial_success", "message": "Some slots confirmed successfully.", "data": [ { "reservationId": 95, "confirmedAt": "2025-05-11T17:19:06.899Z" }, { "reservationId": 96, "error": "Reservation not found." } ], "statusCode": 1002}Sample All Error Response
{ "status": "error", "message": "No slots confirmed successfully.", "data": [ { "reservationId": 95, "error": "Reservation not found." }, { "reservationId": 96, "error": "Reservation expired." } ], "statusCode": 4000}6. Release Slot
To release the slot.
Method: POST
Endpoint: /api/v1/slot/release
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 97 |
Sample Error Response
{ "reservationId": 97}Sample Success Response
{ "status": "success", "message": "Slot released successfully.", "data": { "reservationId": 97, "releasedAt": "2025-05-11T17:32:41.665Z" }, "statusCode": 1000}Sample Error Response
{ "status": "error", "error": "Reservation not found.", "statusCode": 4004}7. Release Slots
To release the slots.
Method: POST
Endpoint: /api/v1/slots/release
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Array Of Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 99 |
Sample Error Response
[ { "reservationId": 99 }, { "reservationId": 100 }]Sample All Success Response
{ "status": "success", "message": "All slots released successfully.", "data": [ { "reservationId": 99, "releasedAt": "2025-05-11T17:40:28.068Z" }, { "reservationId": 100, "releasedAt": "2025-05-11T17:40:28.108Z" } ], "statusCode": 1001}Sample Partial Success Response
{ "status": "partial_success", "message": "Some slots released successfully.", "data": [ { "reservationId": 99, "error": "Reservation not found." }, { "reservationId": 100, "releasedAt": "2025-05-11T17:39:42.366Z" } ], "statusCode": 1002}Sample All Error Response
{ "status": "error", "message": "No slots released successfully.", "data": [ { "reservationId": 99, "error": "Reservation not found." }, { "reservationId": 100, "error": "Reservation expired." } ], "statusCode": 4000}8. Cancel Slot
To cancel the slot.
Method: POST
Endpoint: /api/v1/slot/cancel
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 96 |
Sample Error Response
{ "reservationId": 96}Sample Success Response
{ "status": "success", "message": "Slot cancelled successfully", "data": { "reservationId": 96, "cancelledAt": "2025-05-11T17:45:04.953Z" }, "statusCode": 1000}Sample Error Response
{ "status": "error", "error": "Reservation not found.", "statusCode": 4004}9. Cancel Slots
To cancel the slots.
Method: POST
Endpoint: /api/v1/slots/cancel
Request Headers:
{ "Content-Type": "application/json", "X-Tenant-ID": "Tenant id", "X-User-ID": "User id"}Array Of Request Body Parameters
| Field Name | Type | Mandatory | Description | Example |
|---|---|---|---|---|
| reservation_id | number | Yes | Reservation ID | 94 |
Sample Error Response
[ { "reservationId": 94 }, { "reservationId": 93 }]Sample All Success Response
{ "status": "success", "message": "All slots cancelled successfully.", "data": [ { "reservationId": 94, "cancelledAt": "2025-05-11T17:50:45.813Z" }, { "reservationId": 93, "cancelledAt": "2025-05-11T17:50:45.854Z" } ], "statusCode": 1001}Sample Partial Success Response
{ "status": "partial_success", "message": "Some slots cancelled successfully.", "data": [ { "reservationId": 94, "cancelledAt": "2025-05-11T17:50:07.565Z" }, { "reservationId": 93, "error": "Reservation not found." } ], "statusCode": 1002}Sample All Error Response
{ "status": "error", "message": "No slots cancelled successfully.", "data": [ { "reservationId": 94, "error": "Reservation not found." }, { "reservationId": 93, "error": "Reservation not found." } ], "statusCode": 4000}