Buy on Amazon ~ 1851682627Article of interest
This feature started with version 3.3 of the API and it allows you to update many fields of a product in one call. Prior to this, each attribute for a product was updated in a separate call, causing the process to be a bit slow.
It is important to note that bulk updates only work with JSON formatted data. Because of this, you can leave the mode=json out of your call.
You should use a POST call instead of a GET to avoid over running the length limits that can be found when sending long URLs.
Required Parameters
- keycode - your normal API keycode
- update - the first product you intend to update (more info below)
- field - must be set to *bulk*
Optional Parameters
- test - If you are using GET (please don't) this should be the first parm. Set it to test=1 to avoid saving any actual data.
- imageURL - This is case sensitive. This can be any reachable image in jpg, gif, png format. You can use ftp, http, https and even data URLs here. So rather than pushing in a separate call, we will pull it.
- fields - This is the JSON formatted array of fields to be updated. Yes, this is actually optional. But without it, we won't update any field data.
- errorsonly=1 - If you add this to the request, any fields that update without error not be returned. If multiple products are updated, any product with no errors in any field will be completely omitted.
- dupesok=1 - If you add this to your request, fields that try to update with duplicate values will be considered good and will return "ok" instead of the normal "duplicate" return value.
- returnval=1 - If you add this to your request, the value is returned along with the status for each field you update. Normally the value is omitted to save on data packet size. May be useful when debugging.
Each entry in the fields array is made up of keys and data. Some keys are required and some are optional depending on the data type being used. These entries mirror the single field update calls used when updating data one field at a time.
Details of the fields entries
- field - required, the name of the field to be updated
- value - required, the new value for this field
- extra_id - optional, Some fields use 2 fields to store the data. One being a numeric value and the second being a descriptor [such as a ounces, gallons, quarts] This extra value must match the list we keep in our database. You can include the text version of this extra information at the end of the "value" field but it still needs to match what we have. You can also split the value into two fields the way we do passing the number in the "value" field and the descriptor as an index id in this "extra_id" field. For more information, see the "get=extra" in the basic overview for the v3 API.
- reason - used only when you want to delete a field. If you use this, you must set the value field to empty string and give a reason in this field. At least 13 characters are required for this reason.
An example of the JSON to update multiple fields for a single product
The order of each field in the array doesn't matter. We will process them in sequence but sequence makes no difference. So you don't have to sort them or place them in any partcular order.
You can actually update multiple products at the same time. To do this, you still need to pass some basic information for the first product in the required fields (see above). But in the fields JSON, you create an array of products, each with a fields sub-array. The product listed in the update field would be ignored for the most part but must still be valid. So it can be hardcoded when using this method as long as it is a vaild EAN code.
An example of the JSON to update multiple fields for multiple products
It doesn't matter if you are updating a single product or multiple products. When the response is returned, the top level status is always going to be code 200 assuming your required fields passed the test. Then you will see an array of products even if you only passed in one to be updated. Each product entry and each field entry will have a status so you will know if individual updates worked or failed. This includes the imageURL you passed.
An example of the JSON returned after an update call
The return results in each img or status field
- ok - The field or image processed without error
- n/a - No image was sent (not for fields)
- duplicate - The data you sent already exists. (not for images)
- Any other value is an error which may include details but may not.
Try our data update wizard tool to generate sample code.
Examples of how to update images
Here are two examples of updating images. These both use a GET that you can test in your browser as soon as you insert your keycode. No other fields are being updated in these two examples. You would normally want to use POST in your code because there can be issues with very long GET requests losing data off the end. But these examples will work properly as GET or POST.
This first example is updating a single product image in simple mode using only form variables (no JSON)
https://eandata.com/feed/?test=1&v=3&keycode=[YOUR-CODE]&update=0025192251344&field=*bulk*&imageURL=https://schworak.com/image/0025192251344-Jaws.jpg
This next example is also updating a single product image, but because it is using JSON, you could pass multiple products in the outer "fields" array. Notice that each inner product block also has a "fields" list when using JSON.
https://eandata.com/feed/?test=1&v=3&keycode=[YOUR-CODE]&update=0025192251344&field=*bulk*&fields=[{%22ean%22:%220025192251344%22,%22imageURL%22:%22https://schworak.com/image/0025192251344-Jaws.jpg%22,%22fields%22:[]}]