Bookings API: supported way to link a payment to an appointment, or open the Appointments app checkout from our app?

Questions
1

Hello,

We run an integration for Discovery Town that creates appointments in Square Appointments and takes the payment ourselves. Staff see these appointments on the Square Appointments calendar showing “Unpaid” / “Due” with a “Take Payment” button, even though the customer has already paid in full. We’re worried staff will charge them a second time.

How our integration works

  • Appointment: we create it with the Bookings API (bookings.create), with the customer, team member and service variation, plus a seller note.
  • Payment: it goes through the Orders and Payments APIs. The order uses the same service catalog item as the appointment, and has the customer id. For some in-person payments we use the Point of Sale API (square-commerce-v1://payment/create) with a custom amount.
  • The link: we store the booking id, order id and payment id together on our side. We can’t find a way to tell Square about the link.

What we found

  • The public Bookings API has no order or payment field on a booking, and Orders/Payments have no booking field.
  • Your staff said in the developer forum (most recently October 2026) that the public Bookings API doesn’t expose a booking-to-order or payment relationship.
  • Paying from inside the appointment in the Square Appointments app (“Review and Check Out”) does link the payment, but we can’t trigger that from our system.

Our questions

  1. Is there any supported way (API field, custom attribute, order setting, or similar) to link a payment or order to an appointment so the calendar shows it as paid?
  2. Does the Square Appointments app support a deep link or URL scheme to open the checkout for a specific booking id, similar to the Point of Sale API? If so, where is it documented?
  3. If neither exists, is there a supported way to mark an appointment as paid, or hide the “Take Payment” button for a booking that was paid elsewhere? Is any of this on the roadmap?

Our details

  • Application ID: sq0idp-0iNqHcr8mCHj6cFPwFoQ3Q

  • Merchant ID / location ID: L6QBAGYB13C03

  • Environment: production

  • Example booking id: ydf2tprlgl5zc1

    image
    image442×826 17.5 KB

3

Welcome to the Developer Forum!

Thanks for the detailed write-up. I’m afraid that the public APIs don’t support any of these three options right now: no supported field links an order or payment to a booking, no deep link or URL scheme that opens checkout for a booking ID, and no API to mark an appointment as paid or hides “Take Payment” button.

The practical workaround depends on which workflow you need to preserve. If you keep collecting payment through Discovery Town, use its verified balance as the staff checkout source and add a clear payment-reference warning to the appointment’s seller note (i.e., updating the existing booking’s seller_note through the Bookings API). Please note that this still won’t change Square’s paid indicator or prevent an independent charge there.