Fetch Reservation Payment Schedules

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:

Legacy auto payment rules
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 --location 'https://open-api.guesty.com/v1/listings/:listingId?fields=pms.autoPayments' \
--header 'Authorization: Bearer {token}'

Example response

{
  "_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 --location 'https://open-api.guesty.com/v1/listings?fields=pms.autoPayments&limit=3&skip=0' \
--header 'Authorization: Bearer {token}'

Example response

{
  "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 --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

{
  "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 --location 'https://open-api.guesty.com/v1/quotes/6989e2ddb7404c5981ee1215?mergeAccommodationFarePriceComponents=false&includePaymentsTemplate=true' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}'

Response example extract

{
  "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 --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

{
  "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."