This is pre-release documentation for an API in public beta and is subject to change.
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 are not 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:
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 is not 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:
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
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:
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 is not 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 is not 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.
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.