Learn how to call the Vendors API to retrieve vendors of specified IDs or to search for vendors based on specified query conditions.
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.

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

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

Retrieve Vendor
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/vendors/CARJMAFUWDYBTPO2 \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The successful response returns a payload similar to the following:

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.

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: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "vendor_ids": [
      "CARJMAFUWDYBTPO2",
      "5VPCRLENAFZXFZNA"
    ]
  }'

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:

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.