UpdateBooking rejects CUSTOMER_LOCATION address during team reassignment

Questions
1

We are integrating Square Bookings with a private photography operations app. SearchAvailability succeeds, but UpdateBooking fails when reassigning one service on an existing accepted booking.

Environment: production; Square-Version: 2026-08-19; the business booking profile reports support_seller_level_writes = true. Requests use server-side fetch to PUT /v2/bookings/{booking_id} with a bearer token, Content-Type: application/json, the current booking version, and a persisted idempotency key.

The existing booking has three service segments. We change only the first segment’s team_member_id, preserve all service IDs, versions and durations, and send the complete appointment_segments array. We are not changing the time, creating a booking or changing customer information.

Redacted minimal request (placeholder IDs; actual service versions retained):

{
  "idempotency_key": "REDACTED_UNIQUE_REQUEST_KEY",
  "booking": {
    "version": 1,
    "appointment_segments": [
      {"team_member_id":"TARGET_TEAM_ID","duration_minutes":120,"service_variation_id":"PHOTO_SERVICE_ID","service_variation_version":1779008621141},
      {"team_member_id":"ORIGINAL_TEAM_ID","duration_minutes":10,"service_variation_id":"AERIAL_SERVICE_ID","service_variation_version":1779008621886},
      {"team_member_id":"ORIGINAL_TEAM_ID","duration_minutes":90,"service_variation_id":"VIDEO_SERVICE_ID","service_variation_version":1779008621141}
    ]
  }
}

The response contains four BAD_REQUEST errors with fields address1, city, state and zipcode. Earlier service-removal tests returned the same error fields, with details that address/city/state were blank and ZIP was invalid.

RetrieveBooking before and after the failed call returns version 1, status ACCEPTED, location_type CUSTOMER_LOCATION, and nonempty address_line_1, locality, administrative_district_level_1 and postal_code. We confirmed the booking did not change. The new photographer was shown available by SearchAvailability.

We tried both:

  1. An update containing the unchanged full address plus location_type, location_id, customer_id and start_at.
  2. The sparse update above, omitting all address, customer and location fields.

Both produce the same address-validation rejection. The same problem occurred when removing an unneeded service from other customer-location bookings. We stopped retrying and have not changed addresses or customer profiles to bypass validation.

According to PUT /v2/bookings/{booking_id} - Square API Reference, unspecified attributes should remain unchanged.

Why does changing appointment_segments trigger blank-address validation when the saved customer-location address is complete? Is there a supported request format, required capability, or known API issue? We can provide the actual booking ID, request ID and full diagnostic report privately to Square staff.

2

Additional evidence: a standalone reschedule also fails with the same address validation. This request changes only booking.version and booking.start_at, with a persisted idempotency key; no appointment_segments, customer, location or address fields are sent.

We inspected the original response in the production API logs (Square-Version 2026-08-19). SearchAvailability immediately before it returned HTTP 200, but UpdateBooking returned HTTP 400 with four INVALID_REQUEST_ERROR / BAD_REQUEST entries:

  • address1: “Address can’t be blank”
  • city: “City can’t be blank”
  • state: “State can’t be blank”
  • zipcode: “is not a valid US ZIP code”

RetrieveBooking still shows the original version and scheduled time. We did not retry this mutation while inspecting the logs. This issue therefore affects start-time-only updates as well as segment reassignment/removal. The complete property address remains present in RetrieveBooking. We have retained the trace ID privately for Square staff.