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.

Affiliate.com Bulk Barcode Lookups: Send 100 Links at a Time, Safely graphic

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.

LookupYou sendLimit per requestWhat you get when you go over
url-to-barcodeProduct links100Maximum of 100 URLs are allowed.
barcode-to-skuBarcodes, and one store100Maximum of 100 Barcodes are allowed.
sku-to-barcodeStore SKUs, and one store100Maximum of 100 SKUs are allowed.

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.

Finishing the same 100 linksTime to finish
One batch of 10013 seconds
Four batches of 25, sent together2.1 seconds
Ten batches of 10, sent together1.0 seconds
One hundred single links, 20 at a time2.9 seconds (4 of 100 refused for sending too fast)

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

What you seeRetry?What to do
422 validation failedNo, not as it isFix the addresses it names, or split an oversized list, then send again.
429 too many requestsYes, after a waitWait a random moment, send fewer at once, then retry the same batch.
504 or a timeoutYes, smallerSplit the batch in half and retry each half, so a slow store does not stall all of it.

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

Before a bulk jobDone when
Validate every addressAnything that is not a full http or https URL is dropped and logged before it reaches a batch.
Remove blanks and repeatsEmpty lines are gone and each address appears once.
Skip pages that cannot matchCart, checkout and home pages are filtered out, since they return an empty list.
Group by store for SKUsEach SKU or barcode request names one store.
Choose a batch sizeYou tried 10, 25 and 100 on a sample and picked the one that finishes fastest for your links.
Cap concurrencyNo more than a few requests are in flight at once.
Handle each failure differently422 is fixed, 429 waits, and a timeout is split and retried.
Map results backEvery input, repeats included, ends with a result or a recorded reason.

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.