Applies to: Vendors API
Learn how to create a single vendor or multiple vendors for a Square seller.
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.
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.
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.
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" } }
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.
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.
The successful response to the previous request contains a payload similar to the following:
{ "vendor": { "id": "L2CSGWWIGRQZIPLQ", "created_at": "2021-12-16T00:11:05.522Z", "updated_at": "2021-12-16T00:11:05.522Z", "name": "Vendor 123", "address": { "address_line_1": "505 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "contacts": [ { "id": "JXRHMI4RL47YB7OW", "name": "Joe Burrow", "email_address": "[email protected]", "phone_number": "1-212-555-4250", "ordinal": 0 } ], "account_number": "123456", "version": 1, "status": "ACTIVE" } }
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.
Bulk create vendors
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.
{ "responses": { "0432162f-e3d4-4627-ad5f-f60794f220c3": { "vendor": { "id": "CARJMAFUWDYBTPO2", "created_at": "2021-12-16T03:57:11.128Z", "updated_at": "2021-12-16T03:57:11.128Z", "name": "Vendor 2A", "contacts": [ { "id": "IPSTXCGSCXC5HU2P", "name": "Vendor B's Contact", "email_address": "[email protected]", "phone_number": "1-212-555-4251", "ordinal": 0 } ], "version": 1, "status": "ACTIVE" } }, "0e5785ba-8371-48ed-8317-909edc33a08f": { "vendor": { "id": "5VPCRLENAFZXFZNA", "created_at": "2021-12-16T03:57:11.205Z", "updated_at": "2021-12-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": "[email protected]", "phone_number": "1-212-555-4250", "ordinal": 0 } ], "account_number": "4025391", "note": "a vendor", "version": 1, "status": "ACTIVE" } } } }
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.