Learn how to call the Vendors API to update existing vendors.
Vendors API

Update Vendor Information Beta release
This is pre-release documentation for an API in public beta and is subject to change.

To update information about a vendor, call the UpdateVendor endpoint with a Vendor object containing properties you want to update.

To update multiple vendors at once, call the BulkUpdateVendors endpoint. When you call BulkUpdateVendors, you specify whatever properties that need to be changed in a vendor object and specify that vendor in the map, as the input, with the vendor's ID as the key.

You can update the following properties:

  • The vendor's status

  • The vendor's contact list

  • The vendor's physical address

  • The vendor's name and note

After creating a vendor without specifying any contact, you can call UpdateVendor to add a contact to the vendor. You can also call this endpoint to update an existing contact of the vendor.

The following example shows how to add a new contact to a vendor, as referenced by the 7HRKHFRCOI4U7XDW ID:

Update Vendor
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
curl https://connect.squareupsandbox.com/v2/vendors/{vendor_id} \
  -X PUT \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_ID}",
    "vendor": {
      "id": "7HRKHFRCOI4U7XDW",
      "contacts": [
        {
          "name": "Test Vendor Contact",
          "email_address": "johndoe@acme.com",
          "ordinal": 0
        }
      ],
      "version": 1
    }
  }'

When adding a contact to an existing vendor, do not specify the ID for the new contact. The ID of the new contact is returned when it is added to the vendor.

When updating an existing contact, you must specify the contact ID in the input.

When specifying a contact on the input, you must set an ordinal value that is unique across all contacts of the vendor.

You must specify the current version of the vendor when updating any information of the vendor. You can call the RetrieveVendor endpoint to find out the current version of the vendor.

The successful response returns a payload similar to the following:

Note that the UpdateVendor (or BulkUpdateVendors) endpoint uses the so-called sparse update, where only affected attributes need to be specified in the input to the update request. Unspecified attributes remain unchanged by the update operation.

When you want to add or update addresses for multiple vendors, you can call BulkUpdateVendors to get the addresses added or updated all at once.

The following example adds or updates two vendor addresses:

Bulk Update Vendors
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
curl https://connect.squareupsandbox.com/v2/vendors/bulk-update \
  -X PUT \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "vendors": {
      "7HRKHFRCOI4U7XDW": {
        "idempotency_key": "976ebd7a-7956-4d84-8432-603a68f0c932",
        "vendor": {
          "id": "7HRKHFRCOI4U7XDW",
          "address": {
            "address_line_1": "101 Main Street",
            "address_line_2": "Suite 1",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "10003",
            "country": "US"
          },
          "version": 2
        }
      },
      "CARJMAFUWDYBTPO2": {
        "idempotency_key": "976ebd7a-7956-4d84-8432-603a68f0c933",
        "vendor": {
          "id": "CARJMAFUWDYBTPO2",
          "address": {
            "address_line_1": "102 Minor Street",
            "address_line_2": "Suite 2",
            "locality": "Seattle",
            "administrative_district_level_1": "WA",
            "postal_code": "98105",
            "country": "US"
          },
          "version": 12
        }
      }
    }
  }'

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
{
    "responses": {
        "7HRKHFRCOI4U7XDW": {
            "vendor": {
                "id": "7HRKHFRCOI4U7XDW",
                "created_at": "2022-02-07T20:06:00.544Z",
                "updated_at": "2022-02-08T03:47:32.696Z",
                "name": "Test Vendor Updated",
                "address": {
                    "address_line_1": "101 Main Street",
                    "address_line_2": "Suite 1",
                    "locality": "New York",
                    "administrative_district_level_1": "NY",
                    "postal_code": "10003",
                    "country": "US"
                },
                "contacts": [
                    {
                        "id": "VSRR2WJVVO6LQQ3F",
                        "name": "Test Vendor Contact",
                        "email_address": "johndoe@acme.com",
                        "ordinal": 0
                    }
                ],
                "note": "New note for test vendor",
                "version": 3,
                "status": "ACTIVE"
            }
        },
        "CARJMAFUWDYBTPO2": {
            "vendor": {
                "id": "CARJMAFUWDYBTPO2",
                "created_at": "2021-12-16T03:57:11.128Z",
                "updated_at": "2022-02-08T03:47:32.749Z",
                "name": "Vendor 2A",
                "address": {
                    "address_line_1": "102 Minor Street",
                    "address_line_2": "Suite 2",
                    "locality": "Seattle",
                    "administrative_district_level_1": "WA",
                    "postal_code": "98105",
                    "country": "US"
                },
                "contacts": [
                    {
                        "id": "IPSTXCGSCXC5HU2P",
                        "name": "Vendor 2A's Contact",
                        "email_address": "annie@acme.com",
                        "phone_number": "1-212-555-4251",
                        "ordinal": 0
                    }
                ],
                "note": "More Updated note about vendor ... 2",
                "version": 13,
                "status": "ACTIVE"
            }
        }
    }
}

To update a vendor's name and note, call UpdateVendor while specifying a new name and a new note for a specified vendor.

Suppose you reactivated a vendor and the vendor has rebranded itself. Now you want to change the vendor's name and update the vendor note accordingly. The following example shows how to call UpdateVendor to accomplish these tasks:

Update Vendor
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/vendors/{vendor_id} \
  -X PUT \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "vendor": {
      "id": "7HRKHFRCOI4U7XDW",
      "name": "MicroBrew",
      "note": "Preferred beer supplier.",
      "version": 6
    }
  }'

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
{
    "vendor": {
        "id": "7HRKHFRCOI4U7XDW",
        "created_at": "2022-02-07T20:06:00.544Z",
        "updated_at": "2022-02-22T18:33:12.796Z",
        "name": "MicroBrew",
        "address": {
            "address_line_1": "101 Main Street",
            "address_line_2": "Suite 1",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "10002",
            "country": "US"
        },
        "contacts": [
            {
                "id": "VSRR2WJVVO6LQQ3F",
                "name": "Test Vendor Contact",
                "email_address": "johndoe@acme.com",
                "ordinal": 0
            }
        ],
        "note": "Preferred beer supplier.",
        "version": 7,
        "status": "ACTIVE"
    }
}

To deactivate a vendor, call the UpdateVendor or BulkUpdateVendors endpoint to change the vendor status to INACTIVE.

When deactivated, the vendor is no longer a supplier to the seller and does not receive any more purchase orders from the seller.

The following example deactivates two vendors as referenced by the ID values (CARJMAFUWDYBTPO2 and 7HRKHFRCOI4U7XDW):

Bulk Update Vendors
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
curl https://connect.squareupsandbox.com/v2/vendors/bulk-update \
  -X PUT \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "vendors": {
      "CARJMAFUWDYBTPO2": {
        "idempotency_key": "{UNIQUE_KEY}",
        "vendor": {
          "id": "CARJMAFUWDYBTPO2",
          "status": "INACTIVE",
          "version": 14
        }
      },
      "7HRKHFRCOI4U7XDW": {
        "idempotency_key": "{UNIQUE_KEY}",
        "vendor": {
          "id": "7HRKHFRCOI4U7XDW",
          "status": "INACTIVE",
          "version": 3
        }
      }
    }
  }'

Make sure to use the most recent version numbers in the input to the request. You might want to call BulkRetrieveVendors first to obtain the most recent version numbers of the specified vendors.

The successful response returns a payload similar to the following:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
{
    "responses": {
        "7HRKHFRCOI4U7XDW": {
            "vendor": {
                "id": "7HRKHFRCOI4U7XDW",
                "created_at": "2022-02-07T20:06:00.544Z",
                "updated_at": "2022-02-08T04:02:30.718Z",
                "name": "Test Vendor Updated",
                "address": {
                    "address_line_1": "101 Main Street",
                    "address_line_2": "Suite 1",
                    "locality": "New York",
                    "administrative_district_level_1": "NY",
                    "postal_code": "10003",
                    "country": "US"
                },
                "contacts": [
                    {
                        "id": "VSRR2WJVVO6LQQ3F",
                        "name": "Test Vendor Contact",
                        "email_address": "johndoe@acme.com",
                        "ordinal": 0
                    }
                ],
                "note": "New note for test vendor",
                "version": 4,
                "status": "INACTIVE"
            }
        },
        "CARJMAFUWDYBTPO2": {
            "vendor": {
                "id": "CARJMAFUWDYBTPO2",
                "created_at": "2021-12-16T03:57:11.128Z",
                "updated_at": "2022-02-08T04:02:30.764Z",
                "name": "Vendor 2AA",
                "address": {
                    "address_line_1": "102 Minor Street",
                    "address_line_2": "Suite 2",
                    "locality": "Seattle",
                    "administrative_district_level_1": "WA",
                    "postal_code": "98105",
                    "country": "US"
                },
                "contacts": [
                    {
                        "id": "IPSTXCGSCXC5HU2P",
                        "name": "Vendor B's Contact",
                        "email_address": "annie@acme.com",
                        "phone_number": "1-212-555-4251",
                        "ordinal": 0
                    }
                ],
                "note": "More Updated note about vendor ... 2",
                "version": 15,
                "status": "INACTIVE"
            }
        }
    }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.