Create Vendors for a Square Seller Beta release

Applies to: Vendors APIVendors 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 VendorVendor object in the seller account by calling the CreateVendorCreateVendor or BulkCreateVendorsBulkCreateVendors 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 CreateVendorCreateVendor 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 VendorVendor object, but can be added later by calling the UpdateVendorUpdateVendor endpoint.

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

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.

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": "joe@joesfreshseafood.com",
                "phone_number": "1-212-555-4250",
                "ordinal": 0
            }
        ],
        "account_number": "123456",
        "version": 1,
        "status": "ACTIVE"
    }
}

To create multiple vendors at once, call the BulkCreateVendorsBulkCreateVendors endpoint. The vendors input parameter contains the list of the to-be-created vendors. This parameter is a map of VendorVendor objects. A key of the map is an idempotencyidempotency 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.

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": "annie@acme.com",
                        "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": "joe@acme.com",
                        "phone_number": "1-212-555-4250",
                        "ordinal": 0
                    }
                ],
                "account_number": "4025391",
                "note": "a vendor",
                "version": 1,
                "status": "ACTIVE"
            }
        }
    }
}

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