--- updatedAt: 2026-09-30T16:36:24.000Z agentTools: projectIndex: https://open-api-docs.guesty.com/llms.txt --- # Fetch Reservation Payment Schedules How to retrieve payment schedules per quote or reservations. ## Overview Guesty allows you to configure payment automations to automate the collection of reservation payments when you integrate one of our supported payment processors with your Guesty account. These are now exposed in the API, giving you complete visibility into the payment workflow to reduce guest inquiries about "missing" payments, improve trust through transparent checkout experiences, and enhance financial reporting accuracy. There are two types of automation rules in production: 1. Legacy auto payment rules 2. Newer payment automations We will explain how to retrieve both.
**Deprecation note** While the legacy `pms.autoPayments.policy` object remains for older setups, we strongly recommend migrating the logic to the `paymentWorkflow` array to support users on the new Automation engine.
## Retrieve legacy auto payment rules Use the Retrieve all listings or Retrieve a listing endpoints and map the `pms.autoPayments.policy` object array. You can focus the request by specifying that object as a query parameter. Here are a couple of examples: **Example request to retrieve a single listing's legacy payment rules** ```curl curl --location 'https://open-api.guesty.com/v1/listings/:listingId?fields=pms.autoPayments' \ --header 'Authorization: Bearer {token}' ```
*Example response* ```json { "_id": "string", "pms": { "autoPayments": { "policy": [ { "scheduleTo": { "timeRelation": { "relation": "AT", "unit": "HOURS", "amount": 1 }, "reservationEvent": "CONFIRMATION" }, "_id": "string", "chargeType": "FIXED", "isAuthorizationHold": false, "useGuestCard": true, "amount": 500 }, { "scheduleTo": { "timeRelation": { "relation": "BEFORE", "unit": "DAYS", "amount": 60 }, "reservationEvent": "CHECK_IN" }, "_id": "string", "chargeType": "REST_OF_PAYMENT", "isAuthorizationHold": false, "useGuestCard": false } ] } }, "type": "SINGLE", "tags": [ ], "accountId": "string", "financials": { "channelCommission": { "_id": "string", "accountId": "string", "unitTypeId": "string", "createdAt": "2024-11-12T12:31:48.561Z", "updatedAt": "2024-12-11T05:26:37.340Z", "__v": 0, "useAccountSettings": true, "manual": [ ] } } } ```
**Example request to retrieve multiple listings' legacy auto payment rules** ```curl curl --location 'https://open-api.guesty.com/v1/listings?fields=pms.autoPayments&limit=3&skip=0' \ --header 'Authorization: Bearer {token}' ```
*Example response* ```json { "results": [ { "_id": "string", "pms": { "autoPayments": { "policy": [ ] } }, "tags": [ ], "accountId": "string" }, { "_id": "string", "pms": { "autoPayments": { "policy": [ { "scheduleTo": { "timeRelation": { "relation": "AT", "unit": "HOURS", "amount": 1 }, "reservationEvent": "CONFIRMATION" }, "_id": "string", "chargeType": "FIXED", "isAuthorizationHold": false, "useGuestCard": true, "amount": 500 }, { "scheduleTo": { "timeRelation": { "relation": "BEFORE", "unit": "DAYS", "amount": 60 }, "reservationEvent": "CHECK_IN" }, "_id": "string", "chargeType": "REST_OF_PAYMENT", "isAuthorizationHold": false, "useGuestCard": false } ] } }, "tags": [ ], "accountId": "string" }, { "_id": "string", "pms": { "autoPayments": { "policy": [ { "scheduleTo": { "timeRelation": { "relation": "AT", "unit": "HOURS", "amount": 1 }, "reservationEvent": "CONFIRMATION" }, "_id": "string", "chargeType": "FIXED", "isAuthorizationHold": false, "useGuestCard": true, "amount": 500 }, { "scheduleTo": { "timeRelation": { "relation": "BEFORE", "unit": "DAYS", "amount": 60 }, "reservationEvent": "CHECK_IN" }, "_id": "string", "chargeType": "REST_OF_PAYMENT", "isAuthorizationHold": false, "useGuestCard": false } ] } }, "tags": [ ], "accountId": "string" } ], "title": "Listings Report", "fields": "pms.autoPayments", "limit": 3, "skip": 0, "count": 23 } ```
## Retrieve payment automations schedule #### Key endpoints | Method | URL | Query parameter(s) | | :----- | :------------------------------------------------------------------------------------------------------------------------ | :----------------------------- | | POST | /quotes | `includePaymentsTemplate=true` | | GET | /quotes/:quoteId | `includePaymentsTemplate=true` | | GET | /reservations-v3 | `includePaymentsTemplate=true` |
#### Configure your channel/source If you have not yet created manual bookings with a custom source, create a test reservation specifying that source value. Once this manual channel booking is recognized, activate automation by selecting `manual` as a 'Channel' under your payment automation rule, so the payment schedule applies and appears in quotes when you request it. All manual booking sources are covered. Soon, in an upcoming planned update, you'll have automated payments for each manual source, giving you more control.
### Create a quote example Retrieve calculated schedules during the quoting process to show guests exactly what they will pay and when. **Example request** ```curl curl --location 'https://open-api.guesty.com/v1/quotes?mergeAccommodationFarePriceComponents=false&includePaymentsTemplate=true' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Authorization: Bearer {token}' \ --data '{ "checkInDateLocalized": "2026-03-08", "checkOutDateLocalized": "2026-03-11", "listingId": "62e91d73628c6d0032ebaf9a", "guestsCount": 4, "numberOfGuests": { "numberOfChildren": 2, "numberOfAdults": 2 }, "source": "manual", "ignoreCalendar": false, "ignoreTerms": false, "ignoreBlocks": false }' ```
*Example response paymentWorkflows extract* ```json { "money": { "paymentWorkflow": { "workflow": { "_id": "69821d382e13d6271ac984b0", "name": "Custom", "accountId": "62a06d2f22513000359ee893", "actionTemplates": [ { "actionTemplateId": "740d69dd-5405-518b-b051-5f06784f2ce4", "type": "PAYMENT", "when": { "value": 0, "context": "confirmedAt" }, "conditions": [ ], "details": { "chargeType": "PERCENTAGE", "amount": 7 } }, { "actionTemplateId": "36653fbc-e74a-c385-58f3-2276293bf9e6", "type": "PAYMENT", "when": { "value": 0, "context": "checkOut" }, "conditions": [ ], "details": { "chargeType": "REST_OF_PAYMENT" } } ], "createdAt": "2026-02-03T16:07:20.709Z" } } } } ```
### Retrieve a quote by ID example **Example request** ```curl curl --location 'https://open-api.guesty.com/v1/quotes/6989e2ddb7404c5981ee1215?mergeAccommodationFarePriceComponents=false&includePaymentsTemplate=true' \ --header 'accept: application/json' \ --header 'Authorization: Bearer {token}' ```
*Response example extract* ```json { "money": { "paymentWorkflow": { "workflow": { "_id": "69821d382e13d6271ac984b0", "name": "Custom", "accountId": "62a06d2f22513000359ee893", "actionTemplates": [ { "actionTemplateId": "740d69dd-5405-518b-b051-5f06784f2ce4", "type": "PAYMENT", "when": { "value": 0, "context": "confirmedAt" }, "conditions": [ ], "details": { "chargeType": "PERCENTAGE", "amount": 7 } }, { "actionTemplateId": "36653fbc-e74a-c385-58f3-2276293bf9e6", "type": "PAYMENT", "when": { "value": 0, "context": "checkOut" }, "conditions": [ ], "details": { "chargeType": "REST_OF_PAYMENT" } } ], "createdAt": "2026-02-03T16:07:20.709Z" } } } } ```
### Retrieve a reservation with payment schedule example **Reservation payments schedule example** ```curl curl --location --globoff 'https://open-api.guesty.com/v1/reservations-v3?reservationIds[]=6989ec04a7ccb86c3efc9f72&includePaymentsTemplate=true&mergeAccommodationFarePriceComponents=false' \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' ```
*Reservation response paymentWorkflows extract* ```json { "paymentWorkflow": { "_id": "69821d382e13d6271ac984b0", "templateId": "68f636966e24f29d25ab9491", "name": "Custom", "type": "Payments", "version": 2, "isLatest": true, "accountId": "62a06d2f22513000359ee893", "enabled": true, "trigger": "reservationConfirmed", "conditions": [ { "type": "Platform", "operator": "in", "value": [ "manual" ] }, { "type": "ListingId", "operator": "in", "value": [ "62e91d73628c6d0032ebaf9a" ] } ], "actionTemplates": [ { "actionTemplateId": "740d69dd-5405-518b-b051-5f06784f2ce4", "type": "PAYMENT", "when": { "value": 0, "context": "confirmedAt" }, "conditions": [ ], "details": { "chargeType": "PERCENTAGE", "amount": 7 } }, { "actionTemplateId": "36653fbc-e74a-c385-58f3-2276293bf9e6", "type": "PAYMENT", "when": { "value": 0, "context": "checkOut" }, "conditions": [ ], "details": { "chargeType": "REST_OF_PAYMENT" } } ], "actions": [ { "actionId": "6989ec051ba155428ed6bf3a", "actionTemplateId": "740d69dd-5405-518b-b051-5f06784f2ce4", "executionStatus": "Processing", "scheduledAt": "2026-02-09T14:15:32.759Z", "details": { "chargeType": "PERCENTAGE", "amount": 7 }, "actionType": "PAYMENT" }, { "actionId": "6989ec051ba155428ed6bf3c", "actionTemplateId": "36653fbc-e74a-c385-58f3-2276293bf9e6", "executionStatus": "Pending", "scheduledAt": "2026-03-11T17:00:00.000Z", "details": { "chargeType": "REST_OF_PAYMENT" }, "actionType": "PAYMENT" } ], "createdAt": "2026-02-03T16:07:20.709Z", "createdBy": "Moshe", "applicationPolicy": { "strategy": "Ongoing" }, "__v": 0 } } ```
## Best practices * **Track payment status**: Monitor the status of specific payment actions (e.g., `SCHEDULED`, `SUCCEEDED`, `FAILED`) for existing reservations. Identify complex actions, such as authorization holds and their subsequent captures or releases, using the `actionType` and `dependsOnActionId` fields. * **Validate Payout Coverage**: Guesty Payment Automations require 100% coverage of the reservation total. When displaying these to guests, ensure you show the full breakdown (including holds) to avoid confusion. * **Map dependsOnActionId**: For a better UI experience in guest portals, use this field to visually link a "Security Deposit Hold" to its eventual "Release" or "Capture."