Applies to: Vendors API
Learn how to update information for a single vendor or multiple vendors.
To update information about a vendor, call the UpdateVendor endpoint with a Vendor object containing properties you want to update.
To update multiple vendors at once, call the BulkUpdateVendors endpoint. When you call BulkUpdateVendors, you specify whatever properties that need to be changed in a vendor object and specify that vendor in the map, as the input, with the vendor's ID as the key.
You can update the following properties:
- The vendor's status
- The vendor's contact list
- The vendor's physical address
- The vendor's name and note
After creating a vendor without specifying any contact, you can call UpdateVendor to add a contact to the vendor. You can also call this endpoint to update an existing contact of the vendor.
The following example shows how to add a new contact to a vendor, as referenced by the 7HRKHFRCOI4U7XDW ID:
Update vendor
When adding a contact to an existing vendor, don't specify the ID for the new contact. The ID of the new contact is returned when it's added to the vendor.
When updating an existing contact, you must specify the contact ID in the input. When specifying a contact on the input, you must set an ordinal value that is unique across all contacts of the vendor.
You must specify the current version of the vendor when updating any information of the vendor. You can call the RetrieveVendor endpoint to find out the current version of the vendor.
The successful response returns a payload similar to the following:
{
"vendor": {
"id": "G47IRHQ2YFWYWY5Z",
"created_at": "2021-12-14T04:21:03.606Z",
"updated_at": "2022-02-22T18:13:19.726Z",
"name": "Vendor 1a",
"contacts": [
{
"id": "GYP6Z6HK556PWGZ4",
"name": "Test Vendor Contact",
"email_address": "[email protected]",
"ordinal": 0
}
],
"account_number": "12345a",
"version": 2,
"status": "ACTIVE"
}
}Note that the UpdateVendor (or BulkUpdateVendors) endpoint uses the so-called sparse update, where only affected attributes need to be specified in the input to the update request. Unspecified attributes remain unchanged by the update operation.
When you want to add or update addresses for multiple vendors, you can call BulkUpdateVendors to get the addresses added or updated all at once.
The following example adds or updates two vendor addresses:
Bulk update vendors
{
"responses": {
"7HRKHFRCOI4U7XDW": {
"vendor": {
"id": "7HRKHFRCOI4U7XDW",
"created_at": "2022-02-07T20:06:00.544Z",
"updated_at": "2022-02-08T03:47:32.696Z",
"name": "Test Vendor Updated",
"address": {
"address_line_1": "101 Main Street",
"address_line_2": "Suite 1",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10003",
"country": "US"
},
"contacts": [
{
"id": "VSRR2WJVVO6LQQ3F",
"name": "Test Vendor Contact",
"email_address": "[email protected]",
"ordinal": 0
}
],
"note": "New note for test vendor",
"version": 3,
"status": "ACTIVE"
}
},
"CARJMAFUWDYBTPO2": {
"vendor": {
"id": "CARJMAFUWDYBTPO2",
"created_at": "2021-12-16T03:57:11.128Z",
"updated_at": "2022-02-08T03:47:32.749Z",
"name": "Vendor 2A",
"address": {
"address_line_1": "102 Minor Street",
"address_line_2": "Suite 2",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"postal_code": "98105",
"country": "US"
},
"contacts": [
{
"id": "IPSTXCGSCXC5HU2P",
"name": "Vendor 2A's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4251",
"ordinal": 0
}
],
"note": "More Updated note about vendor ... 2",
"version": 13,
"status": "ACTIVE"
}
}
}
}To update a vendor's name and note, call UpdateVendor while specifying a new name and a new note for a specified vendor.
Suppose you reactivated a vendor and the vendor has rebranded itself. Now you want to change the vendor's name and update the vendor note accordingly. The following example shows how to call UpdateVendor to accomplish these tasks:
Update vendor
{
"vendor": {
"id": "7HRKHFRCOI4U7XDW",
"created_at": "2022-02-07T20:06:00.544Z",
"updated_at": "2022-02-22T18:33:12.796Z",
"name": "MicroBrew",
"address": {
"address_line_1": "101 Main Street",
"address_line_2": "Suite 1",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10002",
"country": "US"
},
"contacts": [
{
"id": "VSRR2WJVVO6LQQ3F",
"name": "Test Vendor Contact",
"email_address": "[email protected]",
"ordinal": 0
}
],
"note": "Preferred beer supplier.",
"version": 7,
"status": "ACTIVE"
}
}To deactivate a vendor, call the UpdateVendor or BulkUpdateVendors endpoint to change the vendor status to INACTIVE.
When deactivated, the vendor is no longer a supplier to the seller and doesn't receive any more purchase orders from the seller.
The following example deactivates two vendors as referenced by the ID values (CARJMAFUWDYBTPO2 and 7HRKHFRCOI4U7XDW):
Bulk update vendors
Make sure to use the most recent version numbers in the input to the request. You might want to call BulkRetrieveVendors first to obtain the most recent version numbers of the specified vendors.
The successful response returns a payload similar to the following:
{
"responses": {
"7HRKHFRCOI4U7XDW": {
"vendor": {
"id": "7HRKHFRCOI4U7XDW",
"created_at": "2022-02-07T20:06:00.544Z",
"updated_at": "2022-02-08T04:02:30.718Z",
"name": "Test Vendor Updated",
"address": {
"address_line_1": "101 Main Street",
"address_line_2": "Suite 1",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10003",
"country": "US"
},
"contacts": [
{
"id": "VSRR2WJVVO6LQQ3F",
"name": "Test Vendor Contact",
"email_address": "[email protected]",
"ordinal": 0
}
],
"note": "New note for test vendor",
"version": 4,
"status": "INACTIVE"
}
},
"CARJMAFUWDYBTPO2": {
"vendor": {
"id": "CARJMAFUWDYBTPO2",
"created_at": "2021-12-16T03:57:11.128Z",
"updated_at": "2022-02-08T04:02:30.764Z",
"name": "Vendor 2AA",
"address": {
"address_line_1": "102 Minor Street",
"address_line_2": "Suite 2",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"postal_code": "98105",
"country": "US"
},
"contacts": [
{
"id": "IPSTXCGSCXC5HU2P",
"name": "Vendor B's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4251",
"ordinal": 0
}
],
"note": "More Updated note about vendor ... 2",
"version": 15,
"status": "INACTIVE"
}
}
}
}