Bulk Barcode Lookups: Send 100 Links at a Time, Safely
The lookups accept up to 100 links, barcodes or SKUs in one request. This guide covers what happens when one is invalid, which batch size finishes fastest, and how to retry, with real responses and a pre-flight checker for your own list.
A lookup that handles one link is simple. A job that handles fifty thousand is not, and the difference is mostly how you batch. The Affiliate.com lookups accept up to 100 links, barcodes or SKUs in a single request, which is what makes bulk barcode lookups practical. This guide is for teams that already use them. It covers what a batch can hold, why one bad address fails the whole request, which batch size finished fastest in our tests, and how to retry. Every response in it is a real one, captured on November 17, 2026, and you can check your own list in the demo below.
What a batch lookup accepts
Three lookups take a list, and each one stops at the same number.
The two SKU lookups name the store once, in the config of the request, and it applies to every item in the batch. A list that spans several stores has to be split by store first. Our guide to barcode lookup goes through what each lookup returns.
What a batch response looks like
Here is the shape of a response. It is a map. Each address you sent is a key, and its value is a list of barcodes. One barcode means a match, an empty list means no match, and several means the page covers more than one product. The meta block counts what went in and what matched.
{
"meta": {
"from": "url",
"to": "barcode",
"from_total": 3,
"to_total": 2
},
"data": {
"https://store-a.example/p/1": [
"0123456789012"
],
"https://store-b.example/cart": [],
"https://store-c.example/p/9": [
"0987654321098"
]
}
}
Two details are easy to miss. Repeated addresses share one result, so six links with two repeats came back as four keys in our test. And to_total counts the matches, which makes a quick check for a batch that mostly missed.
Check a batch before you send it
The demo has two tabs. The pre-flight check takes a list of links, one per line, and shows what the API would do with it: which addresses would fail the request, which are repeats, which are cart or home pages that return an empty list, and how to split what is left into batches. It starts with a list that has problems in it, and you can paste your own. The second tab shows 5 real responses captured on November 17, 2026, including the errors.
The checks follow what the API did in our tests. They are a guide to the shape of a clean batch and not a copy of the API’s own validation, so a link that passes here can still come back as an empty list.
Why one invalid link fails the whole batch
A batch is validated before any of it is looked up. If one address is not a valid URL, or is an empty string, the request returns a 422 and nothing in it is processed. The error lists every problem at once, with its position counted from zero, so you can fix them in one pass.
{
"data.1": [
"The URL field must be a valid URL."
],
"data.4": [
"The URL field must be a valid URL."
],
"data.6": [
"URL can not be empty."
]
}
This is the single biggest reason a bulk job stalls. A list built from real browsing data always contains a few broken addresses, and one of them in every batch turns each request into a refusal. Validate on your side first, drop what fails, and keep a record of what you dropped.
Is 100 the right batch size?
It is the most the API accepts, but in our tests it was not the fastest way to finish. We sent real catalog links to the lookup and timed it. A single link took about 0.2 to 0.3 seconds. A batch of ten took about 2 to 3 seconds. A batch of 100 took between 5.4 seconds and 19 seconds across five runs. The time depends on the stores in the batch and varies from run to run, so treat these as a range and not a promise.
Smaller batches sent together beat one big batch, and there is a limit to that too. When we sent 70 batches of 100 at the same moment, none succeeded: 19 were refused for sending too fast and 51 timed out at the gateway. A batch counted as one request against the rate limit in our test, so the limit and the timeouts are separate problems. Our guide on API rate limits and error handling covers the first.
A sensible starting point is batches of 10 to 25 links with three or four in flight at a time. Use 100 when you are not in a hurry and want the fewest requests. Whatever you choose, cap how many requests you send at once.
Handling a batch that partly matched
Most batches will contain a mix. Treat each address on its own. Save the matches, record the empty lists as no match, and queue the ones that returned several barcodes for a decision about which product was meant. The Universal Gift Registry guide shows how to ask a person to choose, and barcode search explains the identifiers. Do not retry an empty list, because it is an answer and not a failure. A cart page, a home page and a page the catalog does not know all return one.
Map the results back to your own list by address, including the repeats, because the response has one key for several identical inputs. Keep the trace ID of a failed request, which is in the body under meta.trace_id, so support can find it.
Retrying a failed batch
The pattern below puts the pieces together: clean the list, cut it into batches, send a few at a time, and retry what fails. It leaves out the retry helper, which is the backoff code from the rate limits guide.
const isUrl = (s) => { try { const u = new URL(s); return /^https?:$/.test(u.protocol); } catch { return false; } };
function prepare(lines) {
const clean = [...new Set(lines.map((s) => s.trim()))]; // repeats share one result anyway
return clean.filter((s) => isUrl(s)); // one bad address fails the whole request
}
async function lookupAll(lines, { size = 25, parallel = 4 } = {}) {
const urls = prepare(lines);
const batches = [];
for (let i = 0; i < urls.length; i += size) batches.push(urls.slice(i, i + size));
const results = {};
const queue = batches.slice();
const worker = async () => {
for (let batch = queue.shift(); batch; batch = queue.shift()) {
const res = await sendWithRetry(batch); // 429, 504 or a timeout: wait, then retry
Object.assign(results, res.data); // keyed by address
}
};
await Promise.all(Array.from({ length: parallel }, worker));
return lines.map((s) => ({ url: s, barcodes: results[s.trim()] ?? null })); // back to your own order
}
The same approach for barcodes and SKUs
Everything above applies to the two SKU lookups as well: up to 100 items per request, a failure for the whole request if one item is invalid, and results keyed by what you sent. The extra rule is the store. All the items in a request share one store name or address, so group your list by store before you cut it into batches. The store name has to match the catalog, and a name that does not match returns an empty result and not an error.
The checklist
If a job behaves differently for you
Timings depend on the stores in your lists, and every plan sets its own rate limit. If your numbers look very different from these, or you are planning a large job, our team is glad to look at your batch sizes and pacing. Include the trace ID of any request you are asking about. Schedule a call with our team.