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

Upsert booking custom attribute

PUT

 /v2/bookings/{booking_id}/custom-attributes/{key}

Upserts a bookings custom attribute.

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

Path parameters

Example code

Link to section

booking_id

string

Required

The ID of the target booking.

Link to section

key

string

Required

The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

Link to section

Request body

Link to section

custom_attribute

Required

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Value data types.

  • version. To enable optimistic concurrency control for an update operation, include this optional field and specify the current version of the custom attribute.

Link to section

idempotency_key

string

A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

Max Length
45
Link to section

Response fields

Link to section

custom_attribute

The new or updated custom attribute.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

PUT /v2/bookings/{booking_id}/custom-attributes/{key}
curl https://connect.squareup.com/v2/bookings/Z57QXKM2FGXEQDV42W8RBZY7BR/custom-attributes/favoriteShampoo \ -X PUT \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "custom_attribute": { "value": "Spring Fresh" } }'

Response JSON

{ "custom_attribute": { "key": "favoriteShampoo", "version": 1, "updated_at": "2022-11-16T15:50:27Z", "value": "Spring Fresh", "created_at": "2022-11-16T15:50:27Z", "visibility": "VISIBILITY_READ_ONLY" }, "errors": [] }