Vendors API Overview Beta release

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

A seller typically has a list of vendors to supply items for sale. Vendors are also referred to as suppliers. A Square seller can be a vendor for another Square seller, but a vendor might not be a Square seller.

The Seller Dashboard lets a seller add, search, update, or remove a vendor. The Vendors API lets your application manage vendors for a seller. For example, when a new Square seller signs up for your application, your application can call the Vendors API to programmatically add the seller as a supplier for other Square sellers. At a later time, your application can present the vendor list for a seller to choose a supplier to stock a particular type of item. In addition, your application can create an ad hoc vendor and add it to the list of vendors of a Square seller.

Link to section

Data model

The Vendors API exposes the following objects to represent a vendor and the vendor's contact information and to facilitate managing vendors:

• Vendor. An object encapsulating a vendor, including the vendor's name, account number, address, phone number, and associated contacts.

• VendorContact. An object encapsulating a contact associated with a given vendor, including the name, email address, and phone number of a contact for the vendor.

Link to section

Supported Operations

The Vendors API supports the following endpoints and webhook events to enable vendor management operations.

Link to section

Endpoints

• CreateVendor or BulkCreateVendors. Used to create a single vendor or multiple vendors, respectively.

• RetrieveVendor or BulkRetrieveVendors. Used to retrieve the single Vendor object of a specified vendor ID or multiple vendors of a list of specified vendor IDs, respectively.

• UpdateVendor or BulkUpdateVendors. Used to update one or more (batch version) vendors.

• SearchVendors. Used to search for vendors that match specified queried expressions and be sorted in a specified order.

Link to section

Webhooks

The Vendors API supports the following webhook events:

• vendor.created. Notifies of an event when a vendor is created.

• vendor.updated. Notifies of an event when a vendor is updated.

Link to section

Requirements and restrictions

• Your application must have permissions with the OAuth scope of VENDOR_READ or VENDOR_WRITE to call the Vendors API for read or write operations, respectively.