• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
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

Request Body

Example code
Name Description
values
Map<string, BulkUpsertCustomerCustomAttributesRequestCustomerCustomAttributeUpsertRequest>
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.

Response Fields
Name Description
values
Map<string, BulkUpsertCustomerCustomAttributesResponseCustomerCustomAttributeUpsertResponse>

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.
errors
Error [ ]

Any errors that occurred during the request.

Examples

You are viewing an old version of the API
POST /v2/customers/custom-attributes/bulk-upsert
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/customers/custom-attributes/bulk-upsert \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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": "fake-email@squareup.com"
        },
        "customer_id": "70548QG1HN43B05G0KCZ4MMC1G"
      }
    }
  }'
Response JSON 
{
  "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": "fake-email@squareup.com",
        "created_at": "2021-12-09T00:16:20Z"
      }
    }
  }
}