Connect your PMS or software platform to ChannelRUSH to distribute availability, rates and restrictions to booking channels, and bring new, modified and cancelled reservations back into your system.
This guide explains the implementation sequence for CM API v2. Use it alongside the interactive API reference (Swagger UI), which contains the request models, response models and endpoint details. The OpenAPI document is available for client generation, and ReDoc provides another reference view.
The two core flows are:
- Your system → ChannelRUSH → booking channels: send availability, rates and inventory, referred to below as ARI.
- Booking channels → ChannelRUSH → your system: pick up reservations, save them in your system, then confirm that processing succeeded.
This is a server-to-server integration. Keep API credentials on your server, not in a booking page or browser application. If your goal is to search availability and create bookings for a booking website, see the APIs overview for the CRS and OTA APIs instead.
1. Get your test account and connection details
Contact your ChannelRUSH integration contact or support@channelrush.com and request access to the Channel Manager JSON API. Include your platform name, technical contact and the properties/channels you intend to connect.
Before coding against a property, obtain or confirm:
- Test access: the API bearer token and the test properties assigned to your integration. A website login is separate from an API token.
- API server: the test API base is
https://testcm.channelrush.net/api/v2. Use the server and credentials supplied for your environment; do not mix test and production. - Property and product mappings: the
propertyId, room type IDs and rate plan IDs your integration must send. - Enabled processing: which properties can receive ARI from your platform and which are configured for reservation pickup.
- Commercial rules: the property currency, pricing model, supported restrictions, intended booking channels and which system owns availability changes.
- Operational expectations: the reservation polling interval, update volume/batch sizing, credential lifecycle and go-live procedure agreed for your integration.
Your sandbox welcome email includes connection information and a first settings request. Use your assigned values rather than IDs copied from a documentation example. Do not treat a sandbox token as permission to access another test account.
Start with one assigned test property and a small date range. Complete both ARI and reservation processing before expanding to additional properties.
2. Authenticate and make your first request
Send this header on API requests:
Authorization: Bearer YOUR_TOKEN
Send JSON request bodies with Content-Type: application/json and use HTTPS throughout.
Try it in Swagger UI
- Open Swagger UI and select V2.
- Click Authorize.
- In Value, enter the complete value: the word
Bearer, a space, then the token supplied for your integration. Click Authorize, then Close. - Expand
GET /api/v2/connectioncheck, click Try it out, then Execute. - Check the HTTP status, the response's
successfulvalue and anymessages.
Swagger's Execute button sends a real request. Use only your assigned test property when trying write operations such as ariupdate, resconfirm or test_reservationscreate.
The same check from your integration
The following shell examples assume CM_TOKEN contains only the token, without the Bearer prefix. Set those through your normal secure local configuration; do not commit them to source control.
CM_API_BASE='https://testcm.channelrush.net/api/v2'
curl --silent --show-error --include \
"$CM_API_BASE/connectioncheck" \
--header "Authorization: Bearer $CM_TOKEN" \
--header 'Accept: application/json'
HTTP 200 is not sufficient to mark a request successful. Many endpoints return HTTP 200 with successful: false and details in messages. A valid connection check also does not prove that a particular property's mappings or processing modes are enabled.
3. Read and validate the property's mappings
Call POST /api/v2/settings with your assigned propertyId:
{
"propertyId": "YOUR_PROPERTY_ID"
}
You can save this body as settings-request.json, replace the placeholder and send it with:
curl --silent --show-error --include \
"$CM_API_BASE/settings" \
--header "Authorization: Bearer $CM_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @settings-request.json
Require successful: true, then inspect settings.propertyId, settings.propertyName and settings.roomTypes. Each room type includes its roomTypeId, name and available ratePlans.
Build and validate your mapping before sending inventory:
- Match each returned room type to the corresponding room type in your system.
- Match rate plans within the correct room type. Do not assume every room offers the same plans.
- Store the exact string IDs; do not substitute display names, convert codes to numbers or assume they are ChannelRUSH's internal database IDs.
- Refresh and revalidate mappings when rooms or plans change, and before enabling a newly connected property. A plan appearing in settings is not proof that every underlying mapping required for an update is complete; validate your first update too.
GET /api/v2/channels supplies channel names and numeric channel IDs. These channel IDs are consistent across properties, but the list is not proof that every channel is connected to your property.
If settings returns “Settings not configured or enabled.”, confirm the environment, assigned property code and enabled connection with ChannelRUSH before sending updates. Do not guess another property ID.
4. Send a small ARI update
Use POST /api/v2/ariupdate to update inventory. POST /api/v2/ari is a read/report operation, not an update.
An update contains:
propertyId: the mapped property code.channelIds: an optional destination selection. An empty list means all channels in scope, not none. The property's connection, mapping and send settings still determine what can be distributed. Use specific IDs only when deliberately targeting those channels.items: the room/rate-plan updates, each with its owndateRangeand values.
Before changing inventory, read a baseline with POST /api/v2/ari using the property, products and dates you intend to update; an example appears below.
The following is an illustrative request assembled from the API models, not a captured successful transaction. Replace the property/product IDs with settings returned for your test property, choose suitable test dates and confirm the currency. It sets room allocation and a rate-plan price separately. Its empty destination list deliberately uses all-channel scope; for a single-channel test, replace it with the specific numeric channel ID agreed for that property:
{
"propertyId": "YOUR_PROPERTY_ID",
"channelIds": [],
"items": [
{
"roomTypeId": "YOUR_ROOM_TYPE_ID",
"ratePlanId": "",
"allocation": 5,
"dateRange": {
"startDate": "2027-01-10",
"endDate": "2027-01-12",
"mon": true,
"tue": true,
"wed": true,
"thu": true,
"fri": true,
"sat": true,
"sun": true
}
},
{
"roomTypeId": "YOUR_ROOM_TYPE_ID",
"ratePlanId": "YOUR_RATE_PLAN_ID",
"currencyCode": "USD",
"sellRate": 149.00,
"dateRange": {
"startDate": "2027-01-10",
"endDate": "2027-01-12",
"mon": true,
"tue": true,
"wed": true,
"thu": true,
"fri": true,
"sat": true,
"sun": true
}
}
]
}
Save the adjusted body as ari-update.json and send it to $CM_API_BASE/ariupdate with the same authorization and JSON headers, using --data-binary @ari-update.json.
Important update semantics
- The start and end dates are inclusive. The example includes January 10, 11 and 12. These are inventory dates, not a guest's check-in/check-out interval. Preserve the intended calendar dates when using date/time types in a generated client.
- Weekday flags filter the range. A false flag excludes that weekday. The API defaults these flags to true; explicitly setting them avoids client-generator defaults accidentally suppressing updates. At least one weekday must remain true, and the end date cannot precede the start date.
- Send the values you intend to change. Omitted/null update fields do not supply a new value; null is not a clear/reset command. Preserve nullable fields rather than turning every absent value into zero or false.
allocation: 0andstopSell: falseare explicit instructions, not empty values. Each item needs at least one update value. - Use room-level and rate-plan-level scope deliberately. An empty
ratePlanIdis room-level scope; it is not a wildcard rate-plan ID. Use the mapped rate plan when sending a plan's price or restrictions. - Send decimal prices as JSON numbers. Do not include currency symbols or locale-formatted commas.
currencyCodeis required when settingsellRateorrateParams, and item-levelsellRate: 0is rejected. UserateParamsonly when your agreed pricing model needs occupancy or supplemental rates; theRateParameterTypereference defines their meanings, and each type must appear only once per item. - Restriction support varies by destination and setup. Confirm which fields each connected channel accepts before relying on them.
Check the result
Inspect the top-level successful and messages, and every entry in items, including its roomTypeId, ratePlanId, successful and messages. Top-level success can coexist with failed items. A batch must not be treated as an all-or-nothing operation or as successful merely because the HTTP request completed.
Accepted updates are queued for background processing. An immediate readback can precede that processing; do not turn a delayed readback into an automatic duplicate send.
Then use POST /api/v2/ari with the same property, products and dates to inspect stored ARI. For example:
{
"propertyId": "YOUR_PROPERTY_ID",
"roomTypeId": "YOUR_ROOM_TYPE_ID",
"ratePlanId": "YOUR_RATE_PLAN_ID",
"dateRange": {
"startDate": "2027-01-10",
"endDate": "2027-01-12",
"mon": true,
"tue": true,
"wed": true,
"thu": true,
"fri": true,
"sat": true,
"sun": true
}
}
ari reads stored master inventory for your integration, not live OTA inventory. With no channelIds filter it can return both the shared all-channel scope and channel-specific stored scopes; inspect each returned day's channelId as well as its room/plan/date.
Rows can be returned for dates without stored information, and some missing restriction values are displayed as defaults such as false, zero or one night. Do not copy an entire read response back as an update. Construct updates from the values your system actually intends to send.
Readback is not an independent confirmation from every OTA. Separate API processing, stored inventory and downstream channel delivery in your monitoring. For operational investigation, use ChannelRUSH's update status guide or ask your integration contact to check the relevant destination.
After validating the small update, agree the initial inventory horizon and load the required rooms/plans. Then send changes as your system's inventory changes. Keep the ability to reconcile and resend current intended values after an outage; do not replay stale prices over newer changes.
5. Receive reservations and confirm processing
For a new polling integration, implement the paired res and resconfirm endpoints. Do not use a reservation search as a substitute for the pending-delivery workflow.
Pick up pending reservations
Call POST /api/v2/res for each enabled property:
{
"propertyId": "YOUR_PROPERTY_ID"
}
A successful response's items collection contains:
reservation: the booking details and its current status.reservationConfirmationId: the identifier to return when confirming that specific reservation state.
Handle new, modified and cancelled reservations. The JSON reservation status values are 0 = New, 1 = Modified and 2 = Canceled. Process every applicable room and rate entry, not only the first room. Keep the original channel identity and reservation ID alongside your own PMS booking ID.
Do not confuse these identifiers:
reservation.reservationIdidentifies the source reservation; pair it with the property andreservation.channelId, which identifies the booking source.reservation.reservationIdVersionidentifies that reservation state/version.reservationConfirmationIdidentifies the delivery/state you must acknowledge.reservationIdClientis your system's reservation ID, supplied in the confirmation.
Save first, confirm second
For each returned item:
- Validate its property/product mapping and reservation status.
- Save or update the reservation durably in your system, including cancellations.
- Record the delivery identifier and the resulting local booking ID so a repeated pickup does not create another booking.
- Only after successful processing, send that item's confirmation to
POST /api/v2/resconfirm. - Inspect the response's top-level outcome and each confirmation item's
successfulvalue. - Pick up again after confirming a batch to receive later states and remaining work. The API returns bounded batches and exposes successive states of the same booking in order. A short batch does not prove the backlog is exhausted. There is no page/cursor field in
ResRequest.
Illustrative confirmation body; use the actual ID returned by res, not this sample number:
{
"propertyId": "YOUR_PROPERTY_ID",
"items": [
{
"reservationConfirmationId": 12345678910,
"reservationIdClient": "YOUR_PMS_RESERVATION_ID"
}
]
}
A confirmed item no longer appears in the pending pickup collection. Do not confirm an item that failed to save or process. Alert your team and resolve the failure.
Pickup marks pending deliveries as processing; it is not a passive reservation search. Unconfirmed processing items can be returned again. If a delivery remains unconfirmed for 60 minutes from its creation in ChannelRUSH, it becomes eligible for failure/backup processing—not 60 minutes from your first pickup. Repeated polling does not restart that deadline. Once marked unsuccessful, that delivery is no longer in the normal pending pickup set. Backup email depends on configured, verified recipients and does not mean the booking was imported into your PMS. Escalate missing/expired deliveries rather than relying on indefinite redelivery.
Design for interrupted processing
Your system can stop after saving a booking but before receiving a confirmation response. Persist enough state to recognize that delivery on the next pickup and retry its acknowledgement without creating the booking again. A later modification or cancellation is a new state to process, not a duplicate to discard because the source booking ID already exists.
A repeated confirmation can return item-level successful: false after the original confirmation already succeeded. That result alone cannot distinguish an already-confirmed state from another unavailable delivery. Preserve your local record, reconcile the delivery with ChannelRUSH when necessary and never create another booking to resolve an acknowledgement error. A reservation lookup does not itself prove that delivery was acknowledged.
Use property and source-channel context when matching source reservation IDs. Store confirmation IDs without losing 64-bit integer precision. Coordinate workers so the same property's deliveries are not being independently imported by overlapping pollers.
Agree the polling cadence with ChannelRUSH. Monitor last successful pickup, oldest unprocessed delivery, processing failures and failed confirmations. An empty successful pickup means no pending items were returned; an unsuccessful response or timeout must not be recorded as “no bookings.”
6. Test the complete flow
On the test server, POST /api/v2/test_reservationscreate creates test reservations for the configured delivery mode. For the polling workflow, use the same {"propertyId":"YOUR_PROPERTY_ID"} body as res, with only your assigned test property. Then pick up through res, process, confirm through resconfirm and pick up again. This endpoint creates data and notifies ChannelRUSH support; it is not a connection check.
Verify the resulting deliveries, not only the creation response's success flag. Do not expect the creation response to contain the generated reservations, even though Swagger shows a shared reservation-response example. The available test cases depend on property/channel setup; coordinate any missing scenarios with your integration contact.
Before go-live, exercise these scenarios with ChannelRUSH:
- Authentication works, invalid credentials fail and a property with incomplete setup is handled clearly.
- Settings resolve every room/rate-plan combination your system intends to use.
- Allocation, rates and each agreed restriction reach the intended scope; zero, false, omitted values, date boundaries and weekday filters behave as intended.
- A failed item does not hide successful items or cause a whole batch to be marked complete.
- New reservations, modifications, cancellations and multi-room bookings are processed correctly.
- Repeated pickup and a process restart after local save do not duplicate bookings.
- Failed local processing does not send a successful confirmation.
- Failed or uncertain confirmations are recovered without losing later reservation changes.
- An outage recovery uses current intended inventory and drains reservation work without silently dropping it.
Keep sanitized request/response captures from these tests and use them as regression fixtures. Documentation examples are a starting point, not evidence that your own mappings or workflow have passed.
7. Add optional functions only when needed
POST /api/v2/reservations: retrieve existing reservations using the filters inReservationsRequest. An exactreservationIdlookup also requires the booking source'schannelId. Without a reservation ID, the search starts with departure dates 28 days ago, not reservations created in the last 28 days. Use it for agreed lookup/reconciliation work, not to acknowledge pending deliveries.POST /api/v2/book: an optional operation for reservations created in the PMS, such as walk-ins or direct bookings from sources not managed by the channel manager. Do not use it to acknowledge or re-create an OTA booking already received throughres. Agree the intended reservation and inventory workflow before enabling it.POST /api/v2/resall: listed under the deprecated reservation operations. Usereservationsfor existing-reservation lookup andresplusresconfirmfor pending delivery.
If you need push delivery instead of polling, ChannelRUSH can send reservation details to an agreed endpoint on your server. This is not merely a notification to start a poll: your callback must return the agreed confirmation response after processing. Coordinate callback authentication, payload/response shape and retry behavior with ChannelRUSH before implementing it. Do not run overlapping push and polling consumers without agreement.
8. Handle errors and uncertain outcomes
Keep transport errors separate from application results:
- HTTP 400: inspect the validation response and correct the request shape/values. Do not retry an unchanged invalid request in a tight loop.
- HTTP 401: verify the environment and complete
Authorization: Bearer …header. Contact ChannelRUSH if the supplied credential is no longer accepted; do not log or email the token. - HTTP 200 with
successful: false: inspectmessagesand any item-level results. Connection/setup/mapping failures need correction, not an assumption of successful delivery. - HTTP 500, network failure or timeout: the outcome of a write can be uncertain. Use bounded retry/backoff and your persisted operation state. Before replaying ARI, ensure it still represents the newest intended values; before importing or confirming a reservation again, check its recorded processing state.
- Stored ARI differs from an OTA: check destination mapping, supported fields, configured transformations and delivery status. An accepted inbound request is not proof of downstream acceptance.
- A reservation is picked up repeatedly: check whether local processing succeeded and whether the corresponding confirmation succeeded. Do not suppress it by confirming an unprocessed booking.
For support, provide the environment, endpoint, property code, affected product/channel IDs, inventory dates or reservation delivery ID, request time with time zone, HTTP status and sanitized error details. Remove bearer tokens, card details and unnecessary guest data from logs and attachments.
9. Generate a client without losing API semantics
You can generate a client from the OpenAPI document, or implement the endpoints directly. Keep a versioned copy of the specification used to generate your client and review changes before regeneration.
Check the generated client's behavior before using it for inventory or bookings:
- It sends the full bearer header and can switch environments without code changes.
- Nullable values remain distinct from zero/false.
- Date-only inventory examples are not shifted by automatic time-zone conversion.
- Decimal amounts and 64-bit identifiers retain precision.
- It handles
messages, top-level success and item-level success rather than relying only on exceptions for non-2xx responses. - Enum handling and response parsing are verified against actual test responses as well as the models. Reservation statuses are numeric, while
messages[].messageTypeis serialized as text such asInfo,WarningorError; a client generated with a numeric-only message-type parser needs adjustment. Do not assume every illustrative example is a literal successful response.
10. Prepare for production
Coordinate production enablement with your ChannelRUSH integration contact. Confirm the production server/token, property/product mappings, destination channels, supported update fields, reservation delivery settings and operational contacts independently of the sandbox.
Before enabling distribution:
- Agree which system owns allocation and how bookings, cancellations and manual changes affect it, so availability is not adjusted twice.
- Verify the complete initial inventory horizon, including prices and restrictions, for the intended rooms/plans.
- Have reservation pickup, durable processing, confirmation and alerts running for every enabled property.
- Review retry/reconciliation behavior and the support procedure for an uncertain update or delivery failure.
- Validate a controlled production rollout with ChannelRUSH before expanding scope.
Keep test and production configuration separate. Do not move sandbox tokens or sample mapping IDs into production.