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 source
To ensure the payment schedule is returned in the quote, check that your payment automation rules include your intended booking source. If you have not yet created bookings from a custom source, create a test reservation with that source, and it will become available to your payment automation. You will need to update your rules to include it.
We suggest using the default manual as the source and updating it after you've created the reservation. Alternatively, use the origin and originId fields to set a custom source when creating the reservation from the quote.

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