API Guide: Edit An Itinerary
Change an itinerary with PATCH and If-Match, add days, stops, flights and hotels, set images, and delete.
Every change to an existing itinerary carries the version you last read, so two writers never overwrite each other. The token needs itineraries:write.
Steps
Read it and keep the ETag. The ETag header (an opaque version label) of GET /v1/itineraries/{id} is what you send back as If-Match. Use it exactly as received. See Read Itineraries.
Change fields with PATCH /v1/itineraries/{id}. Only the fields you send change. An array you send (days, tags, flights ...) replaces the whole array.
curl -X PATCH https://api.travelyfe.com/v1/itineraries/5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10 \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Travelyfe-Itinerary-Shape: clean" \
-H "If-Match: \"aXRpbmVyYXJ5OjQy\"" \
-H "Idempotency-Key: 6d1c52a8-0b0e-4f3e-8d58-4a1d6a3c2b77" \
-H "Content-Type: application/json" \
-d '{ "title": "Six Days In Lisbon" }'The answer is 200 with the updated itinerary and a new ETag. Use that one for your next change.
Change one part without resending the rest. Each of these also needs If-Match and answers the updated itinerary:
| To | Call |
|---|---|
| Add a day, flight, hotel, packing item or expense | POST /v1/itineraries/{id}/days (or /flights, /hotels, /packing, /expenses) with the item as JSON |
| Change or remove one | PATCH or DELETE /v1/itineraries/{id}/days/{dayId} (/flights/{flightId}, /hotels/{hotelId}, /packing/{itemId}, /expenses/{expenseId}) |
| Add a stop | POST /v1/itineraries/{id}/days/{dayId}/stops |
| Change, move or remove a stop | PATCH or DELETE /v1/itineraries/{id}/days/{dayId}/stops/{stopId}; send dayId in the PATCH body to move it to another day |
curl -X POST https://api.travelyfe.com/v1/itineraries/5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10/days/DAY_ID/stops \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Travelyfe-Itinerary-Shape: clean" \
-H "If-Match: \"aXRpbmVyYXJ5OjQy\"" \
-H "Content-Type: application/json" \
-d '{
"name": "Pastéis de Belém",
"category": "cafe",
"place": { "coordinate": { "latitude": 38.6975, "longitude": -9.2033 } }
}'Set a cover or day image with PUT /v1/itineraries/{id}/cover-image or PUT /v1/itineraries/{id}/days/{dayId}/image. Send a JPEG, PNG or WebP as the body, JSON such as { "query": "lisbon trams" } to have one found, or no body to let the server choose. A JSON url is refused. DELETE on the same address removes it.
Delete with DELETE /v1/itineraries/{id} and If-Match. Only the owner can. It also deletes the itinerary's images and documents for everyone it is shared with, and cannot be undone. The answer is 204.
What You Get
The updated itinerary and its new ETag after every write (except delete). Hotel check-in and check-out times are set by the server and cannot be changed.
If It Doesn't Work
428 preconditionRequired: you sent noIf-Match, or a value the API did not give you.409 itineraryModified: the itinerary changed since you read it. The response carries the currentETag. Read it again, reapply your change and retry.403 subscriptionRequired: the change touchespackingorexpensesand the traveller does not have Pro.403 forbidden: the token lacksitineraries:write.404 notFound: no such itinerary, day, stop or item.422 validationFailed:documentscannot be sent here (use the document routes), or a field is wrong;details.fieldnames it.422 imageRejected: the image could not be used.413 itineraryTooLarge: the itinerary is over 256 KB.
Limits
- Writes count against 60 requests a minute; image uploads against 20.
- Itinerary limits are the same as on create.