Vendors API

Retrieve Vendors of Specified IDs Beta release

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

If you know the ID of a Vendor object, you can call the RetrieveVendor or BulkRetrieveVendors endpoint to retrieve the vendor object. The BulkRetrieveVendors endpoint can take more than one vendor ID to retrieve multiple vendors at a time.

Retrieve a single vendor at a time
Retrieve multiple vendors at a time

Link to section
Retrieve a single vendor at a time

To retrieve a single vendor, call RetrieveVendor while specifying the vendor's ID value as the vendor_id path parameter value.

Link to section
Request: Retrieve a single vendor at a time

The following example shows how to call RetrieveVendor to retrieve a vendor of a known vendor ID:

Retrieve Vendor

curl https://connect.squareupsandbox.com/v2/vendors/CARJMAFUWDYBTPO2 \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Link to section
Response: Retrieve a single vendor

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

{
    "vendor": {
        "id": "CARJMAFUWDYBTPO2",
        "created_at": "2022-01-16T03:57:11.128Z",
        "updated_at": "2022-01-16T03:57:11.128Z",
        "name": "Vendor 2A",
        "contacts": [
            {
                "id": "IPSTXCGSCXC5HU2P",
                "name": "Vendor B's Contact",
                "email_address": "annie@acme.com",
                "phone_number": "1-212-555-4251",
                "removed": false,
                "ordinal": 0
            }
        ],
        "version": 1,
        "status": "ACTIVE"
    }
}

Link to section
Retrieve multiple vendors at a time

To retrieve multiple vendors at a time, call BulkRetrieveVendors while specify the IDs of the vendors in the vendors_ids list of the request payload.

Link to section
Request: Retrieve multiple vendors at a time

The following example retrieves two vendors with the CARJMAFUWDYBTPO2 and 5VPCRLENAFZXFZNA IDs:

Bulk Retrieve Vendors

1
2
3
4
5
6
7
8
9
10
11

curl https://connect.squareupsandbox.com/v2/vendors/bulk-retrieve \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "vendor_ids": [
      "CARJMAFUWDYBTPO2",
      "5VPCRLENAFZXFZNA"
    ]
  }'

Link to section
Response: Retrieve multiple vendors at once

When successful, the response returns a payload similar to the following, where the responses object is a map of vendors indexed by the vendor ID:

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

{
    "responses": {
        "5VPCRLENAFZXFZNA": {
            "vendor": {
                "id": "5VPCRLENAFZXFZNA",
                "created_at": "2022-01-16T03:57:11.205Z",
                "updated_at": "2022-01-16T03:57:11.205Z",
                "name": "Vendor A",
                "address": {
                    "address_line_1": "101 Main Street",
                    "address_line_2": "Suite 1",
                    "locality": "City",
                    "administrative_district_level_1": "State",
                    "postal_code": "10003",
                    "country": "US"
                },
                "contacts": [
                    {
                        "id": "HB5S4SB2EXYGKVJ3",
                        "name": "Vendor A's Contact",
                        "email_address": "joe@acme.com",
                        "phone_number": "1-212-555-4250",
                        "removed": false,
                        "ordinal": 0
                    }
                ],
                "account_number": "4025391",
                "note": "a vendor",
                "version": 1,
                "status": "ACTIVE"
            }
        },
        "CARJMAFUWDYBTPO2": {
            "vendor": {
                "id": "CARJMAFUWDYBTPO2",
                "created_at": "2022-01-16T03:57:11.128Z",
                "updated_at": "2022-01-16T03:57:11.128Z",
                "name": "Vendor 2A",
                "contacts": [
                    {
                        "id": "IPSTXCGSCXC5HU2P",
                        "name": "Vendor B's Contact",
                        "email_address": "annie@acme.com",
                        "phone_number": "1-212-555-4251",
                        "removed": false,
                        "ordinal": 0
                    }
                ],
                "version": 1,
                "status": "ACTIVE"
            }
        }
    }
}

If you specify an invalid or non-existing vendor ID in the input parameter of vendor_ids in the BulkRetrieveVendors request call, as illustrated:

{
    "vendor_ids":  ["CARJMAFUWDYBTPO2", "5VPCRLENAFZXFZNA_"]    
}

The response returns a payload similar to the following, where the found vendor (CARJMAFUWDYBTPO2) is returned as expected, but for the invalid or non-existing vendor ID (5VPCRLENAFZXFZNA_) an error is returned:

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

{
    "responses": {
        "5VPCRLENAFZXFZNA_": {
            "errors": [
                {
                    "category": "INVALID_REQUEST_ERROR",
                    "code": "NOT_FOUND",
                    "detail": "Resource not found."
                }
            ]
        },
        "CARJMAFUWDYBTPO2": {
            "vendor": {
                "id": "CARJMAFUWDYBTPO2",
                "created_at": "2022-01-16T03:57:11.128Z",
                "updated_at": "2022-01-16T03:57:11.128Z",
                "name": "Vendor 2A",
                "contacts": [
                    {
                        "id": "IPSTXCGSCXC5HU2P",
                        "name": "Vendor B's Contact",
                        "email_address": "annie@acme.com",
                        "phone_number": "1-212-555-4251",
                        "removed": false,
                        "ordinal": 0
                    }
                ],
                "version": 1,
                "status": "ACTIVE"
            }
        }
    }
}

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

Retrieve Vendors of Specified IDs Beta release

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

On this page

Link to section
Retrieve a single vendor at a time

Link to section
Request: Retrieve a single vendor at a time

Link to section
Response: Retrieve a single vendor

Link to section
Retrieve multiple vendors at a time

Link to section
Request: Retrieve multiple vendors at a time

Link to section
Response: Retrieve multiple vendors at once

On this page

Retrieve Vendors of Specified IDs Beta release This is pre-release documentation for an API in public beta and is subject to change.

On this page

Link to section Retrieve a single vendor at a time

Link to section Request: Retrieve a single vendor at a time

Link to section Response: Retrieve a single vendor

Link to section Retrieve multiple vendors at a time

Link to section Request: Retrieve multiple vendors at a time

Link to section Response: Retrieve multiple vendors at once

On this page

Retrieve Vendors of Specified IDs Beta release

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

Link to section
Retrieve a single vendor at a time

Link to section
Request: Retrieve a single vendor at a time

Link to section
Response: Retrieve a single vendor

Link to section
Retrieve multiple vendors at a time

Link to section
Request: Retrieve multiple vendors at a time

Link to section
Response: Retrieve multiple vendors at once