Bulk upsert customer custom attributes

POST

/v2/customers/custom-attributes/bulk-upsert

Creates or updates custom attributes for customer profiles as a bulk operation.

Use this endpoint to set the value of one or more custom attributes for one or more customer profiles. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateCustomerCustomAttributeDefinition endpoint.

This BulkUpsertCustomerCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a customer ID and custom attribute. Each upsert response is returned with the ID of the corresponding request.

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

Permissions:CUSTOMERS_WRITE

Guide

Bulk upsert customer custom attributes

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 BulkUpsertCustomerCustomAttributes 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 customer_id and custom_attribute or an errors field.

Link to section

errors

Any errors that occurred during the request.

curl https://connect.squareup.com/v2/customers/custom-attributes/bulk-upsert \ -X POST \ -H 'Square-Version: 2024-12-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "values": { "id1": { "custom_attribute": { "key": "favoritemovie", "value": "Dune" }, "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id2": { "custom_attribute": { "key": "ownsmovie", "value": false }, "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id3": { "custom_attribute": { "key": "favoritemovie", "value": "Star Wars" }, "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id4": { "custom_attribute": { "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808", "value": "10.5" }, "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id5": { "custom_attribute": { "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail", "value": "[email protected]" }, "customer_id": "70548QG1HN43B05G0KCZ4MMC1G" } } }'

{ "values": { "id2": { "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "ownsmovie", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": false, "created_at": "2021-12-09T00:16:20Z" } }, "id1": { "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "favoritemovie", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "Dune", "created_at": "2021-12-08T23:14:47Z" } }, "id3": { "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "favoritemovie", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "Star Wars", "created_at": "2021-12-09T00:16:20Z" } }, "id4": { "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "10.5", "created_at": "2021-12-08T23:14:47Z" } }, "id5": { "customer_id": "70548QG1HN43B05G0KCZ4MMC1G", "custom_attribute": { "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "[email protected]", "created_at": "2021-12-09T00:16:20Z" } } } }