One product, one GS1 identifier

Every integration project runs into the same confusion in its first week, and it is worth settling before anything is configured: the number your company uses to order, pick and invoice a product is usually not the number the world uses to identify it. A product needs exactly one GS1 identifier, and that identifier is the GTIN. It identifies the model — the article as such, the thing a shopper would call "this shirt in size M, in blue" — not the individual garment on the shelf and not the box it arrived in.

If your master data calls this field EAN, nothing is missing. EAN and GTIN are the same key under two names: EAN is the older European term, GTIN the current global one, and a thirteen-digit EAN-13 is a GTIN-13. When you see a GTIN written with fourteen digits, that is the same key padded on the left with a zero so that all trade-item keys share one length.

How a GTIN is built

A GTIN is not an opaque serial number. It is composed of three parts, and reading them apart explains most of what the connector does with it:

9 5 2 1 2 3 4   0 0 0 1 2   9
└─── prefix ─┘  └─ item ─┘  └ check digit
                 reference

The GS1 Company Prefix (the base number) is licensed to one company and identifies it globally. The item reference is yours to assign: you decide that 00012 is the linen shirt, and nobody outside your company has a say in it. The final digit is a check digit computed from all the others, so that a mistyped key almost always announces itself rather than quietly pointing at somebody else's product.

What the digits do not tell you is where the prefix ends. Company prefixes vary in length, and 9521234000129 could in principle carry a seven-digit or a nine-digit prefix. That boundary comes from the GS1 GCP Length Table, which the platform reads from the same openepcis-epc-digitallink-translator toolkit that supplies its identifier grammar; no connector reimplements it and none guesses it.

The SKU is your number, not GS1's

The SKU is the article number your house assigns to itself. It is the key your PIM or ERP stores its record under, the string your colleagues quote on the phone, and — this is the part that surprises people — it has no GS1 meaning whatsoever. Sometimes a SKU happens to be a GTIN, because the business bought the goods with a manufacturer's EAN and adopted it as its own record key. Sometimes a SKU contains the item reference of the GTIN, because someone chose the numbering that way years ago. And in a great many houses the SKU is LIN-SHIRT-BLUE-M, an internal ordering scheme with a history of its own, related to nothing.

So the connector never assumes. Instead, each adapter knows where its host system keeps the GS1 key, and the SKU's role is stated in the connection's configuration rather than inferred.

In UnoPim the SKU is the record's unique key and the PIM knows nothing of GS1, so one option decides everything: source.options.gtin-from takes composed, sku or an attribute code. Under composed — the default — the connector builds the GTIN itself from the company prefix configured as the connection's target.gcp-prefixes, the SKU as the item reference, and the check digit, left-padding to twelve data digits. Under sku, the SKU is the complete GTIN, which is the right setting for traded goods that arrived with a foreign EAN, where composing would be wrong because the base number is not yours. Under an attribute code, usually dpp_gtin, the key lives in a field of its own — the setting for SKUs that are not numeric or not derived from the prefix.

Composing raises one question a PIM forces on you: SKUs are unique, but a batch of a product shares its model's GTIN. Under composed, the connector reads only the part of the SKU in front of the first hyphen as the item reference — always the first, so 95201-DE-L240815 also reduces to 95201 — and 95201 and 95201-L240815 therefore compose the same key 9521234952015. The suffix does no more than keep the two records distinct in UnoPim. Which batch the second record stands for is stated in an attribute of its own — dpp_batch_identifier by default, configurable as source.options.batch-from — rather than parsed back out of the SKU; a record that carries a batch number is published only at its instance path as an LGTIN, never as the model record, so batch master data cannot overwrite the model's.

This splitting happens in the UnoPim adapter and only under composed. Under sku and under an attribute code the value is taken as the key exactly as it stands, hyphens and all, and no article number is cut out of it. The other adapters read their key from a field of their own and have no comparable SKU arithmetic at all — batches there do not depend on how a SKU is written.

In ERPNext the key comes from the Item's barcodes child table: rows are read in table order, and the first row with a GS1-family barcode_type whose value passes the check digit wins. A row with the right type and a broken check digit is skipped rather than treated as fatal, so one mistyped legacy barcode cannot hide a correct one below it. In metasfresh the GTIN lives in the product's ean field, and a GLN in the gln of a business partner's locations — again, the first one that survives the check digit.

When there is no GTIN

A record without a publishable key is skipped, and only that record: the connector logs which record it was and what was wrong with the key, advances the cursor, and carries on with the batch. One unpublishable article must not sink the two hundred behind it. Under composed, UnoPim refuses loudly and specifically — no SKU, no configured prefix, more than one prefix (the connector will not pick one for you), a non-numeric SKU, or a prefix and reference that together exceed the available digits. A tenant licensed for several prefixes is a normal case, not an error: list them all as target.gcp-prefixes, keep the keys in the source system and point source.options.gtin-from at the attribute that holds them. Only composing is ruled out, not multiple prefixes — ownership is decided across all of them.

That leaves the question of where a first GTIN comes from, and the answer is not the connector. The UnoPim plugin's panel offers a product without a key two equally prominent paths: draw the next number from your own prefix pool, or deposit a GTIN you already have. Both go through the platform: drawing calls the bridge's POST /v1/identifiers/allocate, and depositing sends the typed number to the bridge first, refusing it in the bridge's own words when the verdict reports a data problem. Where the key turns out to sit on the tenant's own prefix and the connection composes, what gets written is the item reference into the SKU rather than a second copy of the whole number — so the product keeps one place where its identity lives.

Model, batch, item, and the pallet they travel on

Once the model has its GTIN, everything more specific is that GTIN plus a qualifier. This is the vocabulary the rest of this chapter relies on.

The GTIN is what you need for anything said about the article in general, and it is the level at which registries ask their questions: brand name, GPC category and a product description are required of a model, never of a batch. It is also the only level a PIM contributes, because a PIM describes articles.

An LGTIN is a GTIN qualified by a batch or lot number, and despite naming something narrower it is still a class: a batch is a quantity of goods, not one thing, which is why an EPCIS event reports it as an epcClass in a quantityList rather than in the epcList. Use it for anything that is true of a production run — a manufacturing date, a best-before date, a certificate covering that run. The catalog stores it as its own instance document beneath the model's GTIN, with the qualifier stated inside the document as a term as well as standing in the path. The term in the document is what the resolver derives the per-instance anchor from, and the anchor is what makes ?linkType=masterData stop at the batch instead of redirecting up to the model. The Java connectors do not leave that to inference: after every instance write they register a gs1:masterData link on the instance anchor explicitly, because the resolver merges linksets from the most specific anchor downwards and a model-level entry would otherwise always win. Batches reach the catalog from ERPNext's Batch DocType, from UnoPim's dpp_batch_identifier, and from Odoo's lots.

An SGTIN is a GTIN qualified by a serial number, and that one is an individual thing — one battery, one appliance — so an event names it in the epcList. Use it wherever a warranty, a repair history or an individual passport has to attach to a single item. ERPNext feeds this level from its Serial No records, and Odoo from those stock.lot records whose product is tracked by unique serial number — the same record type that yields a batch when the product is tracked by lot. A PIM does not feed it at all, because a PIM has no serialised goods to describe. A record can also carry both qualifiers at once, which the catalog addresses as /01/{gtin}/10/{lot}/21/{serial}.

An SSCC identifies neither an article nor a piece of it but the logistics unit — this carton, this pallet, this roll cage — and it is the one GS1 number a company always assigns entirely itself: an extension digit, your company prefix, a serial reference of your choosing and a check digit, eighteen digits in all. It never identifies what is inside; it identifies the packed unit, and the link between the two is made by an aggregation event whose parentID is the SSCC. Odoo mints one when a package is created — deliberately at creation, not at the first event, so that earlier events already have something to name the unit by.

Finally, a note that saves an afternoon of confusion: a serial number that was never registered as its own document still resolves. The resolver walks up to the nearest level it does know and serves the model's links, so an unregistered item behaves like the model rather than like a dead link.

The check digit, and what the bridge answers

The check digit is the cheapest correctness test there is, and the connectors apply it everywhere a key enters the system: weight three on the rightmost data digit alternating leftwards, sum, and the check digit is what brings that sum up to a multiple of ten. 952123400012 gives 9, so 9521234000129 is a well-formed key and 9521234000123 is not.

That arithmetic is one of several statements the bridge makes about an identifier. When an adapter asks it to resolve a key, the answer is not a boolean but a verdict, and each part of it is separately meaningful: whether the value matches the grammar of its Application Identifier, whether the check digit agrees, where the company prefix ends, whether that prefix is yours, how far the Verified by GS1 lookup got, who GS1 says licenses the key, and the canonical Digital Link that all of this adds up to. Every offline statement — syntax, check digit, prefix boundary, canonical link — is computed before anything can fail, so it stands even on a call where the registry never answered.

Read the verdict's reason before its booleans. A verdict marks dataProblem only when a person editing the record can actually fix what is wrong; an unreachable registry, an expired credential or a spent quota make the verdict degraded, not the data wrong. A user interface that renders "invalid" from an unfinished registry lookup accuses your colleagues of bad data every time a token expires, which is why the connectors branch on dataProblem and never on the registry status.

Own prefix, foreign prefix

The prefix boundary answers a second question beyond where the number ends: whether the key sits inside a prefix your tenant is licensed for. own_prefix says it does — you issued this key, and no external lookup is needed to know who it belongs to. foreign_prefix says the key is perfectly valid but belongs to somebody else, which is the normal state of a supplier's article in your catalogue; that is the case where a registry call is worth making, because only GS1 can say who the licensee is. unknown says no prefix boundary could be established at all, so ownership is simply undecidable and nothing should be concluded from it.

The distinction has practical consequences beyond display. Ownership decides whether a lookup happens at all, and it decides commissioning: where a product has not explicitly said otherwise, the connector mints an EPCIS commissioning event only for keys on a prefix the tenant is licensed for. Announcing that you brought a supplier's article into existence is not a claim you want a connector making on your behalf.