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
To retrieve a single vendor, call RetrieveVendor while specifying the vendor's ID value as the vendor_id
path parameter value.
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:
curl https://connect.squareupsandbox.com/v2/vendors/CARJMAFUWDYBTPO2 \
-H 'Square-Version: 2023-01-19' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
Response: Retrieve a single vendor
The successful response returns a payload similar to the following:
Copy
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"
}
}
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.
Request: Retrieve multiple vendors at a time
The following example retrieves two vendors with the CARJMAFUWDYBTPO2
and 5VPCRLENAFZXFZNA
IDs:
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"
]
}'
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:
Copy
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:
Copy
{
"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:
Copy
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"
}
}
}
}