Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Booking Custom Attributes

  • List booking custom attribute definitions

  • Create booking custom attribute definition

  • Delete booking custom attribute definition

  • Retrieve booking custom attribute definition

  • Update booking custom attribute definition

  • Bulk delete booking custom attributes

  • Bulk upsert booking custom attributes

  • List booking custom attributes

  • Delete booking custom attribute

  • Retrieve booking custom attribute

  • Upsert booking custom attribute

  • Webhooks

  • booking.custom_attribute_definition.owned.created

  • booking.custom_attribute_definition.owned.deleted

  • booking.custom_attribute_definition.owned.updated

  • booking.custom_attribute_definition.visible.created

  • booking.custom_attribute_definition.visible.deleted

  • booking.custom_attribute_definition.visible.updated

  • booking.custom_attribute.owned.deleted

  • booking.custom_attribute.owned.updated

  • booking.custom_attribute.visible.deleted

  • booking.custom_attribute.visible.updated

<- Booking Custom Attributes API

Booking Custom Attributes API

All versions ->

Bulk upsert booking custom attributes

POST

 /v2/bookings/custom-attributes/bulk-upsert

Bulk upserts bookings custom attributes.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_WRITE and APPOINTMENTS_WRITE for the OAuth scope.

For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to Appointments Plus or Appointments Premium.

Permissions:APPOINTMENTS_WRITE
Try in API Explorer
Link to section

Request body

Example code

Link to section

values

Required

A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertBookingCustomAttributes request and the information needed to create or update a custom attribute.

Link to section

Response fields

Link to section

values

A map of responses that correspond to individual upsert requests. Each response has the same ID as the corresponding request and contains either a booking_id and custom_attribute or an errors field.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/bookings/custom-attributes/bulk-upsert
curl https://connect.squareup.com/v2/bookings/custom-attributes/bulk-upsert \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "values": { "id1": { "custom_attribute": { "key": "favoriteShampoo", "value": "Spring Fresh" }, "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id2": { "custom_attribute": { "key": "ownsShampoo", "value": false }, "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id3": { "custom_attribute": { "key": "favoriteShampoo", "value": "Hydro-Cool" }, "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id4": { "custom_attribute": { "key": "hasShoes", "value": true }, "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id5": { "custom_attribute": { "key": "partySize", "value": "4" }, "booking_id": "70548QG1HN43B05G0KCZ4MMC1G" } } }'

Response JSON

{ "values": { "id2": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "hasShoes", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": false, "created_at": "2022-11-16T00:16:20Z" }, "errors": [] }, "id1": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "favoriteShampoo", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "Spring Fresh", "created_at": "2022-11-16T00:14:47Z" }, "errors": [] }, "id3": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "favoriteShampoo", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "Hydro-Cool", "created_at": "2022-11-16T00:16:20Z" }, "errors": [] }, "id4": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "partySize", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": 4, "created_at": "2022-11-16T00:14:47Z" }, "errors": [] }, "id5": { "booking_id": "70548QG1HN43B05G0KCZ4MMC1G", "custom_attribute": { "key": "celebrating", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "birthday", "created_at": "2022-11-16T00:16:20Z" }, "errors": [] } }, "errors": [] }