Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB
CustomerCustomAttributes

BulkUpsertCustomerCustomAttributes

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.

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

Request body

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

Example request

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

Success

valuesobject

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.

Example response

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