Go-UPC API for AI Agents: Barcode and Product Data Lookup

Here is the thing that will catch you, and it is why this post leads with a warning instead of setup instructions.

If you send Go-UPC a barcode with digits missing, it does not reject it. It infers the missing digits, looks up whatever product that completed code belongs to, and returns an ordinary 200 OK with a name, a brand, an image, a category and an ingredients list. The only sign anything unusual happened is one boolean near the bottom of the response: "inferred": true.

For a human running one lookup in a browser, that is a convenience. For an agent reading barcodes out of photos, where a smudged digit or a bad crop is completely routine, it is a machine for generating confident wrong answers. Your agent asks what product this is, gets a detailed response with no error anywhere in it, and tells someone their warehouse received 400 jars of a queso they have never stocked.

So: check inferred on every single response, and treat true as "I do not know what this is" rather than as an answer. That one check is worth more than everything else in this post.

With that out of the way, the rest of the API is pleasant, genuinely simple, and unusual in one important respect: it has no writes at all. There is nothing to delete, nothing to overwrite, no customer to accidentally email. Which means the engineering problem here is not safety. It is correctness and cost.

What Go-UPC actually is

One endpoint. You give it a barcode, it gives you a product. That is the whole surface area, and it is refreshing after a week of APIs with four hundred methods.

# Production: Bearer token in the header
curl -X GET \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  https://go-upc.com/api/v1/code/829576019311

# Also supported: key as a query parameter. Fine for a quick test,
# wrong for anything real — query strings end up in logs and proxies.
curl 'https://go-upc.com/api/v1/code/829576019311?key=YOUR_API_KEY'

Use the header. The query-parameter form exists for convenience while testing, and the docs themselves recommend the header for production. An agent improvising a request from documentation it half-remembers will reach for the query string, which is one more reason to not let it build the call by hand: the key should be injected by something that always gets this right. More on that in API access control for AI agents.

The barcode formats, and why the distinction matters

Go-UPC accepts four code types, and they are all GTINs with different digit counts. People use the names loosely, which is exactly how an agent ends up validating a barcode against the wrong pattern and rejecting a perfectly good code.

The response tells you which one it matched in a codeType field. Worth reading rather than assuming, particularly if you are reconciling against your own product master, because a GTIN-14 on a case and a GTIN-13 on the units inside it are different codes for related things, and conflating them will quietly inflate your counts by whatever the case quantity is.

The leading zero problem

In Go-UPC's own documented example, the request is made for 781138811156 and the response comes back with "code": "0781138811156". Thirteen digits out for twelve digits in.

This is normal in barcode land, because a UPC-A is an EAN-13 with a leading zero, and different systems normalise in different directions. It is also exactly the kind of thing that breaks an agent, because the obvious correctness check is to compare the code you sent with the code you got back, and that check now fails on a correct response.

Normalise both sides before comparing: strip leading zeros, or pad everything to 14 digits, and be consistent about which. And note the response also carries product.upc and product.ean as numbers rather than strings, which will drop leading zeros again if you round-trip them through anything that treats them as integers. Barcodes are identifiers, not quantities; keep them as strings everywhere in your own code.

The response shape, and the field that will trip up a model

{
  "code": "0781138811156",
  "codeType": "UPC",
  "product": {
    "name": "On the Border Queso, Jalapeno, Spicy - 15.25 Ounce",
    "description": "New On The Border Jalapeno Queso is made with Real Cheese...",
    "imageUrl": "https://go-upc.s3.amazonaws.com/images/99132458.jpeg",
    "brand": "On the Border",
    "specs": [
      ["Organic", "No"],
      ["Non-GMO", "No"],
      ["Height", "4.88 In"],
      ["Width", "4.0 In"],
      ["Length", "4.0 In"]
    ],
    "category": "Dips & Spreads",
    "categoryPath": ["Food, Beverages & Tobacco", "Food Items", "Dips & Spreads"],
    "ingredients": { "text": "Water, Monterey Jack Cheese..." },
    "upc": 781138811156,
    "ean": 781138811156
  },
  "barcodeUrl": "https://go-upc.com/barcode/781138811156",
  "inferred": false
}

Look at specs. It is an array of two-element arrays, not an object. So product.specs.Height is undefined, and a model writing code against this will reach for that spelling almost every time, because every other API it has ever seen would have made that an object.

The keys also vary by industry. A food product has Organic and Non-GMO; an electronics item will have something else entirely. So there is no fixed set to code against, and specs is better treated as a bag of labelled strings you search than as a structure you index. If you need one specific attribute reliably across a catalogue, read it from your own product master and use Go-UPC for identification, not for specifications.

Response validation is what keeps this from becoming a class of silent bug. Every call is checked against the method's schema before the result reaches the model, so a shape that does not match is caught at the boundary rather than surfacing three steps later as a confidently wrong summary. The same guard catches the thing described in 200 OK with an error in the body.

One more useful field: categoryPath is a Google Shopping taxonomy path, which means it is a standard vocabulary rather than Go-UPC's own invention. If you are classifying products, that path is considerably more useful than the single category string, and it maps onto taxonomies your other systems may already speak.

Two requests per second, and why that number is the whole design

Go-UPC caps you at two requests per second. Higher limits are available on request, but assume two until somebody has agreed otherwise in writing.

Two per second is very low by the standards of the APIs in this series, and agents are the worst possible shape of traffic for it. An agent handed a photo of a shelf, or a delivery note with sixty line items, will try to look all of them up at once, because nothing in its reasoning suggests that it should not. You will hit 429 on the third call, and then on the retry, and the whole task will crawl or fall over.

Three things make this work properly.

1. Serialise deliberately. Sixty barcodes is thirty seconds of lookups, and that is fine. Build the workflow so the agent submits a batch and reads results when they are ready, rather than blocking a conversation on a loop it cannot speed up.
2. Back off on 429. Retries with exponential backoff and jitter happen automatically on rate-limit responses, which is what stops a burst turning into a stampede of retries that keeps you permanently throttled. The mechanics are in the retries guide.
3. Cache, which is the real answer. See below, because this deserves its own section.

Cache everything, forever, and stop paying twice

Most API data is a snapshot of something that changes. A balance moves, a ticket gets reassigned, a pipeline finishes. Barcode data is not like that. A GTIN is a permanent identifier for a specific product in specific packaging. The name, brand, dimensions and ingredients behind 0781138811156 will be the same next year as they are today, and if the manufacturer changes the recipe materially they will typically issue a new code.

Which makes this one of the few APIs where an aggressive, long-lived cache is not a compromise. It is just correct. Look up each barcode once, store the whole response, and never pay for it again.

And it is paying, literally. The Developer plan is $74.95 a month for 5,000 lookups, which is about one and a half cents per call. The Startup plan is $245 for 45,000, and Enterprise is $795 for 450,000. Those are monthly quotas, not soft limits: exceed them and you get 429 the same as hitting the per-second cap.

So an agent in a retry loop on a barcode that does not resolve is not wasting compute, it is spending money, roughly a cent and a half a go. A hundred pointless retries overnight is a real line item, and more importantly it eats the quota you needed for actual work. This is the clearest case in the series for watching your own call volume rather than assuming it is fine, which is what API observability for AI agents is about.

404 is data, not a failure

Go-UPC claims over 500 million products, which sounds comprehensive until you remember how many barcodes exist in the world. Private-label goods, regional products, small producers, anything very new, anything industrial: plenty of valid barcodes have no entry. A 404 here means "this is a real code and we do not have it," which is a completely different statement from "something went wrong."

Agents handle this badly by default. A 404 looks like a failure, and the instinct baked into most retry logic is to try again. But retrying a 404 will never succeed, and each attempt costs you a lookup. The agent burns quota proving a negative.

The right behaviour is to record the miss, cache it as a miss so you do not look it up again tomorrow, and carry on with a clearly labelled unknown. The four status codes worth distinguishing:

• 400 — the code is not a recognised format. Your scanner or OCR produced something malformed. Fix the input, do not retry.
• 401 — authentication failed. A key problem, not a data problem, and retrying will not help.
• 404 — valid code, no product. Normal. Cache the miss and move on.
• 429 — either the two-per-second cap or your monthly quota. The only one of the four where retrying is the right answer, and only with backoff.

Note the docs do not define a JSON error body for any of these, so do not write code that parses an error object out of a 404. Read the status.

Setting it up

npx swytchcode
swy login
swy init --mode=sandbox

swy get go-upc
swy auth connect go-upc        # API key; the Bearer header is applied for you
swy auth status

swy discover "look up a product by barcode" --project go-upc
swy list methods go-upc

swy info <canonical_id>        # read the response schema before you build
swy add method <canonical_id>

Shorter than usual, because there is only one thing to allowlist. Keep --project go-upc on the discover call, and run swy get before swy info or info will report a real method as missing. Do read the schema from swy info rather than working from the docs, specifically so the specs array shape is in front of you while you write the parsing code.

The API key goes into a local encrypted store outside your project and is injected at call time, so it never reaches the model's context and cannot be echoed back inside a product description. No .env file, and no key sitting in a query string in your logs. See the authentication docs.

Policy, when there is nothing destructive to guard

This API has no writes, so the usual approval-gate story does not apply. What policy is for here is cost control, which is a use people forget about.

{
  "id": "cap-barcode-lookups-per-run",
  "target": ["<go-upc lookup canonical_id>"],
  "when": { "field": "call_count", "operator": ">", "value": 200 },
  "action": {
    "type": "REQUIRES_APPROVAL",
    "message": "Agent has made 200 barcode lookups in this run — confirm before continuing"
  },
  "approval_timeout": "1h"
}

The failure mode worth guarding is an agent that decides to enrich your entire 40,000-line product catalogue because someone asked it to "fill in the missing product names." That is a plausible instruction, a reasonable interpretation, and $600 of lookups. A ceiling per run turns it into a question instead of an invoice. Check the fields available on your method with swy info and the operators in the policy reference; held calls go to Slack or Telegram and fail closed, so nothing runs away while you are asleep. Setup is in the human approval docs.

Because the rules live in your repo, the spend ceiling on this integration is a reviewed pull request rather than a setting somebody changed in a dashboard. That is the argument in policy-as-code for AI agents, and it applies to budget exactly as it applies to safety.

Idempotency, briefly

A lookup is a read, so there is no duplicate-write risk: calling it twice creates nothing. But it does cost twice, which makes the idempotency key useful for a different reason than usual. Keyed on the barcode, a repeated lookup inside a run collapses onto the first result instead of spending another credit, and a retry after a timeout does not double-charge you. Background in API idempotency: the complete guide and the idempotency docs.

The audit log earns its keep here too. swy audit network gives you every lookup with its barcode and response, which is both your cost breakdown and your answer to "where did this product name come from." When a catalogue entry turns out to be wrong, that log tells you whether the agent invented it or Go-UPC inferred it. See how to log every API call an AI agent makes.

Using it from Claude

Through the MCP server in Claude Desktop you can hand over a photo of a product, have the barcode read, and get the catalogue data back in one exchange, which is a nice demo and an honestly useful workflow for anyone doing data entry. In Claude Code it is more often part of a script: enrich this CSV, fill in these names, flag the ones you could not identify. Setup per client is in the MCP setup guide, the reference is in the MCP docs, and skills.md hands a coding agent the commands to wire it up itself.

One instruction worth putting in your system prompt, because it is the single highest-value sentence you can add: if inferred is true, say the barcode could not be read reliably and do not report the product. Models will otherwise present inferred results with exactly the same confidence as exact matches, because nothing in the response looks like a warning.

For an always-on service rather than an editor session, the Anthropic SDK guide has a working tool-use loop you can build the batching and caching around.

What you can build

1. Catalogue enrichment that admits what it does not know. Take a product list with nothing but barcodes and fill in names, brands, categories and images, writing results into Airtable or Notion. The valuable part is the second column it produces: the barcodes it could not resolve and the ones that only matched by inference, which is the list a human should actually look at.
2. Goods-received checking. Scan what arrived, look each code up, compare against the purchase order, and report mismatches. Watch the GTIN-14 versus GTIN-13 distinction here, because cases and units are where these reconciliations go wrong, and pair it with a quantity sanity check rather than trusting the match alone.
3. Allergen and ingredient screening. The ingredients.text field makes it possible to flag products containing something you need to avoid across a whole order. Be careful about how you present this: ingredient data from any third-party database can be stale or incomplete, so this is a tool for flagging items to check, never a safety guarantee to show an end customer.
4. Shelf and photo audits. Read barcodes out of store photos, identify what is on the shelf, and compare against the planogram. This is the use case where the inferred check matters most, because photographed barcodes are partially obscured all the time.
5. A product-data questioning tool for support. A customer sends a photo of what they bought; the agent identifies it and pulls the dimensions and specs. Combine with a support desk integration and the agent answers "will this fit" without a human looking anything up.
6. Duplicate detection in your own catalogue. Normalise every barcode you hold to 14 digits, look up the ones you have no data for, and surface the entries that are the same product listed twice under UPC and EAN forms of the same GTIN. A one-off job that usually finds more than people expect.

FAQ

What does inferred mean in a Go-UPC response?

It means you sent an incomplete code and Go-UPC filled in the missing digits before looking it up. The product returned may well not be the product you scanned. Treat inferred: true as an unresolved lookup, not a result.

What is the Go-UPC API rate limit?

Two requests per second, plus a monthly lookup quota set by your plan: 5,000 on Developer, 45,000 on Startup, 450,000 on Enterprise. Both return 429 when exceeded. Higher per-second limits are available on request.

Why am I getting a 404 for a barcode that definitely exists?

Because the code is valid but not in the database. Private-label, regional, industrial and very new products are frequently missing from any product database, including one with 500 million entries. Do not retry; record it as an unknown and cache the miss.

Can I cache Go-UPC responses?

Yes, and you should, indefinitely. A GTIN identifies a specific product in specific packaging, so the data behind it does not meaningfully change; material changes usually get a new code. Given that each lookup costs around one and a half cents on the entry plan, caching is the difference between a sensible bill and a silly one. Check the terms of your plan for any restriction on storing the data.

Why is product.specs.Height undefined?

specs is an array of [key, value] pairs, not an object, so you have to search it rather than index into it. The keys also differ by product category, so do not assume any particular one is present.

What is the difference between UPC, EAN and GTIN?

GTIN is the umbrella term. A UPC is a GTIN-12, an EAN is a GTIN-13, EAN-8 is a GTIN-8, and GTIN-14 is used on cases rather than individual units. A UPC is the same number as its EAN-13 form with a leading zero, which is why the code you send and the code you get back can differ by one digit.

Does the agent need write access to anything?

Not for Go-UPC, which is read-only by nature. The writes in these workflows happen in whatever system you put the enriched data into, and that is where approval gates belong. The pattern is in human-in-the-loop approval for AI agent tool calls.

Is Go-UPC the right choice over other barcode APIs?

Compare on coverage for your specific catalogue rather than on headline product counts, because the number that matters is the hit rate on your barcodes, not anyone's total. Take a sample of 200 codes you actually handle, including the awkward regional and private-label ones, and run them through a trial key. Coverage claims are marketing; a hit rate on your own sample is evidence.

The short version

Check inferred on every response. Treat 404 as an answer rather than an error, and never retry it. Respect two requests per second and design the workflow around batches instead of loops. Cache every result forever, because the data does not change and each lookup costs real money. Keep barcodes as strings and normalise before comparing. And remember that specs is an array of pairs, whatever your model assumes.

Get those six right and this is one of the easiest integrations you will build, precisely because nothing it can do is destructive. The only thing it can damage is your confidence in your own data, and that only happens if you let an inferred match through unlabelled.

Related reading

• Go-UPC integration page
• API Idempotency: The Complete Guide
• API Observability for AI Agents
• Policy-as-Code for AI Agents
• SendGrid API for AI Agents
• Browse all 300+ API integrations