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

Add or update a vendor's contact information
Add or update multiple vendor addresses
Update a vendor's name and note
Deactivate multiple vendors

Link to section
Add or update a vendor's contact information

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.

Link to section
Request: Add a vendor's contact information

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: 2023-03-15' \
  -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": "[email protected]",
          "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.

Link to section
Response: Add or update a vendor's contact information

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

{
    "vendor": {
        "id": "G47IRHQ2YFWYWY5Z",
        "created_at": "2021-12-14T04:21:03.606Z",
        "updated_at": "2022-02-22T18:13:19.726Z",
        "name": "Vendor 1a",
        "contacts": [
            {
                "id": "GYP6Z6HK556PWGZ4",
                "name": "Test Vendor Contact",
                "email_address": "[email protected]",
                "ordinal": 0
            }
        ],
        "account_number": "12345a",
        "version": 2,
        "status": "ACTIVE"
    }
}

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.

Link to section
Add or update multiple vendor addresses

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.

Link to section
Request: Add or update multiple vendor addresses

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: 2023-03-15' \
  -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
        }
      }
    }
  }'

Link to section
Response: Add or update multiple vendor addresses

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": "[email protected]",
                        "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": "[email protected]",
                        "phone_number": "1-212-555-4251",
                        "ordinal": 0
                    }
                ],
                "note": "More Updated note about vendor ... 2",
                "version": 13,
                "status": "ACTIVE"
            }
        }
    }
}

Link to section
Update a vendor's name and note

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

Link to section
Request: Update a vendor's name and note

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: 2023-03-15' \
  -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
    }
  }'

{
    "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": "[email protected]",
                "ordinal": 0
            }
        ],
        "note": "Preferred beer supplier.",
        "version": 7,
        "status": "ACTIVE"
    }
}

Link to section
Deactivate multiple vendors

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.

Link to section
Request: Deactivate multiple vendors

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: 2023-03-15' \
  -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.

Link to section
Response: Deactivate multiple 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": "[email protected]",
                        "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": "[email protected]",
                        "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.

Update Vendor Information Beta release

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

On this page

Link to section
Add or update a vendor's contact information

Link to section
Request: Add a vendor's contact information

Link to section
Response: Add or update a vendor's contact information

Link to section
Add or update multiple vendor addresses

Link to section
Request: Add or update multiple vendor addresses

Link to section
Response: Add or update multiple vendor addresses

Link to section
Update a vendor's name and note

Link to section
Request: Update a vendor's name and note

Link to section
Response: Update a vendor's name and note

Link to section
Deactivate multiple vendors

Link to section
Request: Deactivate multiple vendors

Link to section
Response: Deactivate multiple vendors

On this page

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

On this page

Link to section Add or update a vendor's contact information

Link to section Request: Add a vendor's contact information

Link to section Response: Add or update a vendor's contact information

Link to section Add or update multiple vendor addresses

Link to section Request: Add or update multiple vendor addresses

Link to section Response: Add or update multiple vendor addresses

Link to section Update a vendor's name and note

Link to section Request: Update a vendor's name and note

Link to section Response: Update a vendor's name and note

Link to section Deactivate multiple vendors

Link to section Request: Deactivate multiple vendors

Link to section Response: Deactivate multiple vendors

On this page

Update Vendor Information Beta release

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

Link to section
Add or update a vendor's contact information

Link to section
Request: Add a vendor's contact information

Link to section
Response: Add or update a vendor's contact information

Link to section
Add or update multiple vendor addresses

Link to section
Request: Add or update multiple vendor addresses

Link to section
Response: Add or update multiple vendor addresses

Link to section
Update a vendor's name and note

Link to section
Request: Update a vendor's name and note

Link to section
Response: Update a vendor's name and note

Link to section
Deactivate multiple vendors

Link to section
Request: Deactivate multiple vendors

Link to section
Response: Deactivate multiple vendors