Create Vendors for a Square Seller

Applies to: Vendors API

Learn how to create a single vendor or multiple vendors for a Square seller.

Link to section

Overview

To add a vendor to a seller account, create a Vendor object in the seller account by calling the CreateVendor or BulkCreateVendors endpoint. The CreateVendor endpoint creates a single vendor at a time, while BulkCreateVendors creates multiple vendors at a time.

When creating a vendor, you must specify at a minimum the name and status. Optionally, you can specify an address for the vendor or one or more contact persons for the vendor. You can also assign the vendor an account number or add a custom note about the vendor.

Link to section

Add a vendor with the most basic information

To create a vendor with the most basic information, call the CreateVendor endpoint, specifying the vendor's name and status and, optionally, assigning an account ID.

With this basic operation, the vendor's address or contacts aren't present in the resulting Vendor object, but can be added later by calling the UpdateVendor endpoint.

Link to section

Request: Create a vendor without an address or contacts

The following example creates a vendor with the most basic information, including the vendor's name and status:

Create vendor

The vendor name must be unique across the seller account. If the name attribute value is the same as an existing vendor name, you get a 400 BAD_REQUEST response stating that the name attribute value isn't unique.

Link to section

Response: Create a vendor without an address or contacts

The successful response to the simple vendor creation request contains a payload similar to the following:

{ "vendor": { "id": "G47IRHQ2YFWYWY5Z", "created_at": "2021-12-14T04:21:03.606Z", "updated_at": "2021-12-14T04:21:03.606Z", "name": "Vendor 1", "account_number": "12345", "version": 1, "status": "ACTIVE" } }
Link to section

Create a vendor with an address and contacts

If an address is known or contacts are known, you can specify them in the input when calling CreateVendor. The following example shows how to create a vendor while specifying the vendor's address and a contact.

Link to section

Request: Create a vendor with an address and contacts

Create vendor

For the vendor's address, you use address_line_1 or address_line_2 for the vendor's street address, locality for the city, and administrative_district_level_1 for the state or province.

A vendor can have more than one contact. In the contacts list of a vendor, each contact entry must have an ordinal value. You can use this ordinal value to sort contacts.

Link to section

Response: Create a vendor with an address and contacts

The successful response to the previous request contains a payload similar to the following:

Link to section

Create multiple vendors at once

To create multiple vendors at once, call the BulkCreateVendors endpoint. The vendors input parameter contains the list of the to-be-created vendors. This parameter is a map of Vendor objects. A key of the map is an idempotency key used to ensure that the object isn't duplicated no matter how many times the object creation is attempted.

If a specified vendor object shares the name with another vendor object, the specified vendor object isn't created. Other specified vendor objects can be successfully created in a call to BulkCreateVendors, as long as their names are unique among themselves and other existing vendor objects. Bulk operations differ from batch operations in that the former permits partial successes, whereas the latter does not.

You can use BulkCreateVendors to add a single vendor by making the vendors map contain a single idempotency_key-object pair.

Link to section

Request: Create two vendors at once

Bulk create vendors

Link to section

Response: Create two vendors at once

The successful response returns a payload similar to the following.

The responses field is an object map containing idempotency_key-vendor pairs. The key is the same as specified in the request and the object is the corresponding Vendor object just created.

If you call the same BulkCreateVendors request again, you get the same previous response. You can call SearchVendors, querying against the vendors' name values, to verify that no duplicate vendor objects are created by repeated calls to BulkCreateVendors.