POST /v1.1/search/promotions
Search for available promotions for a specific sailing and stateroom subcategory. Returns promotion details including refundability policy and currency.
Request
POST /v1.1/search/promotions
Request Body
{
"departure": {
"date": "20261205"
},
"itinerary": {
"code": "07D519",
"ship": {
"code": "RH"
}
},
"guests": {
"adults": 2,
"children": 0
},
"stateroom_subcategory": {
"code": "4B"
}
}
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
departure.date | string | Yes | Departure date (YYYYMMDD format) |
itinerary.code | string | Yes | Itinerary code |
itinerary.ship.code | string | Yes | Ship code |
guests.adults | integer | Yes | Number of adult guests |
guests.children | integer | Yes | Number of child guests |
stateroom_subcategory.code | string | Yes | Stateroom subcategory code |
Example Request
curl -X POST "https://api.rccl.ro/v1.1/search/promotions" \
-H "X-WorldTravel-ApiKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"departure": { "date": "20261205" },
"itinerary": { "code": "07D519", "ship": { "code": "RH" } },
"guests": { "adults": 2, "children": 0 },
"stateroom_subcategory": { "code": "4B" }
}'
Response
200 OK
Returns an array of promotion resources with related objects included.
Response body:
{
"data": [
{
"type": "promotion",
"id": "890f60f2-0c6b-36f1-8e3e-beda3d5aed41",
"attributes": {
"departure": "2026-12-05",
"open": true,
"air_restricted": true
},
"relationships": {
"stateroom_subcategory": {
"links": {
"related": "/v1.1/stateroom_subcategory/55523f76-70a2-3ea9-8e77-e68cb819c503"
},
"data": {
"type": "stateroom_subcategory",
"id": "55523f76-70a2-3ea9-8e77-e68cb819c503"
}
},
"company": {
"links": {
"related": "/v1.1/company/2a15e462-7710-332a-b536-2ef4731d9dad"
},
"data": {
"type": "company",
"id": "2a15e462-7710-332a-b536-2ef4731d9dad"
}
},
"ship": {
"links": {
"related": "/v1.1/ship/9508a19d-7801-307e-a7b7-628c31bfdd47"
},
"data": {
"type": "ship",
"id": "9508a19d-7801-307e-a7b7-628c31bfdd47"
}
},
"promotion_category": {
"links": {
"related": "/v1.1/promotion_category/caa2791a-60cc-3086-9d37-05b9b521fbd9"
},
"data": {
"type": "promotion_category",
"id": "caa2791a-60cc-3086-9d37-05b9b521fbd9"
}
},
"currency": {
"links": {
"related": "/v1.1/currency/a055562b-db59-3d8b-a9cc-680367308118"
},
"data": {
"type": "currency",
"id": "a055562b-db59-3d8b-a9cc-680367308118"
}
}
},
"links": {
"self": "/v1.1/promotion/890f60f2-0c6b-36f1-8e3e-beda3d5aed41"
}
}
],
"meta": {
"count": 1
},
"included": [
{
"type": "ship",
"id": "9508a19d-7801-307e-a7b7-628c31bfdd47",
"attributes": {
"code": "RH",
"title": "Rhapsody of the Seas",
"description": "..."
},
"links": {
"self": "/v1.1/ship/9508a19d-7801-307e-a7b7-628c31bfdd47"
}
},
{
"type": "company",
"id": "2a15e462-7710-332a-b536-2ef4731d9dad",
"attributes": {
"code": "RCC",
"title": "Royal Caribbean International\u00ae",
"description": "..."
},
"links": {
"self": "/v1.1/company/2a15e462-7710-332a-b536-2ef4731d9dad"
}
},
{
"type": "stateroom_subcategory",
"id": "55523f76-70a2-3ea9-8e77-e68cb819c503",
"attributes": {
"code": "4B",
"color": "94D0E8",
"title": "Cabina spatioasa cu balcon cu vedere la ocean",
"description": "...",
"surface_area": 18,
"balcony_area": 3,
"image_url": "https://ik.imagekit.io/worldtravel/wp-content/uploads/2019/03/RH_Cabina_4B.jpg"
},
"relationships": {
"ship": {
"data": {
"type": "ship",
"id": "9508a19d-7801-307e-a7b7-628c31bfdd47"
}
},
"facility": {
"links": {
"related": "/v1.1/facility/d4dd111a-4fd9-3339-8238-aca5c05bebe3"
},
"data": {
"type": "facility",
"id": "d4dd111a-4fd9-3339-8238-aca5c05bebe3"
}
}
},
"links": {
"self": "/v1.1/stateroom_subcategory/55523f76-70a2-3ea9-8e77-e68cb819c503"
}
},
{
"type": "facility",
"id": "d4dd111a-4fd9-3339-8238-aca5c05bebe3",
"attributes": {
"title": "ROYAL CARIBBEAN INTERNATIONAL - CABINE",
"description": "..."
},
"links": {
"self": "/v1.1/facility/d4dd111a-4fd9-3339-8238-aca5c05bebe3"
}
},
{
"type": "promotion_category",
"id": "caa2791a-60cc-3086-9d37-05b9b521fbd9",
"attributes": {
"code": "BESTRATE",
"description": "Best Rate",
"displayed_description": "Cel mai mic tarif disponibil."
},
"relationships": {
"company": {
"data": {
"type": "company",
"id": "2a15e462-7710-332a-b536-2ef4731d9dad"
}
},
"refundability": {
"links": {
"related": "/v1.1/refundability/e1e1d3d4-0573-327e-9ee0-480caf1283d6"
},
"data": {
"type": "refundability",
"id": "e1e1d3d4-0573-327e-9ee0-480caf1283d6"
}
}
},
"links": {
"self": "/v1.1/promotion_category/caa2791a-60cc-3086-9d37-05b9b521fbd9"
}
},
{
"type": "refundability",
"id": "e1e1d3d4-0573-327e-9ee0-480caf1283d6",
"attributes": {
"code": "R",
"description": "Tarife cu depozit rambursabil"
},
"links": {
"self": "/v1.1/refundability/e1e1d3d4-0573-327e-9ee0-480caf1283d6"
}
},
{
"type": "currency",
"id": "a055562b-db59-3d8b-a9cc-680367308118",
"attributes": {
"code": "EUR",
"symbol": "\u20ac"
},
"links": {
"self": "/v1.1/currency/a055562b-db59-3d8b-a9cc-680367308118"
}
}
],
"jsonapi": {
"version": "1.0"
}
}
Promotion Attributes
| Field | Type | Description |
|---|---|---|
departure | string | Departure date (ISO 8601) |
open | boolean | Whether the promotion is currently open for booking |
air_restricted | boolean | Whether air travel restrictions apply |
Relationships
| Relationship | Type | Cardinality | Description |
|---|---|---|---|
stateroom_subcategory | stateroom_subcategory | one | The stateroom subcategory this promotion applies to |
company | company | one | Operating cruise line |
ship | ship | one | The ship |
promotion_category | promotion_category | one | The promotion category (e.g. Best Rate) |
currency | currency | one | Pricing currency |
Included Resource Types
| Type | Description |
|---|---|
ship | Ship details |
company | Cruise line details |
stateroom_subcategory | Subcategory details (color, surface area, image) |
facility | Facility/amenity group |
promotion_category | Promotion category with description and refundability |
refundability | Refundability policy |
currency | Currency code and symbol |
Error Responses
| Status | Description |
|---|---|
401 | Unauthorized — missing or invalid API key |
500 | Internal Server Error — upstream query failure |