Docs for passport platforms

dpp-backup.com offers the life cycle calls of EN 18222. A platform sends passports with CreateDPP and UpdateDPPById, and four read calls answer from the copy. Every stored version comes back with a receipt signed with Ed25519.

The basics

  • Address: https://dpp-backup.com/api/v1
  • Credential: Authorization: Bearer <credential>. The brand creates the connection in its portal and gives you the credential. It leads to that brand's copy and nowhere else.
  • Body: JSON, at most 1,048,576 bytes.
  • Paths: as in EN 18222 Table 16. Percent-encode an id in the path.

Sending passports

EN 18222 callRequestAnswer
CreateDPP (4.6)POST /api/v1/dpps with the whole passport201 and the stored version
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} with the parts that changed200 and the passport as stored
DeleteDPPById (4.8)DELETE /api/v1/dpps/{dppId}Always 405. A back-up copy is kept for the life of the passport.

An update is a JSON merge patch (RFC 7396), as EN 18222 8.1 suggests. A null removes a member. The patch is merged into the newest stored version, and the result is stored as the next version. If the merged passport is not valid, nothing is stored.

What a passport must have

The attributes of EN 18223 Table 1:

  • digitalProductPassportId: a string of at most 500 characters. It cannot change in an update.
  • uniqueProductIdentifier: for example a GS1 Digital Link address.
  • granularity: model, batch or item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived or invalid. Only published passports are backed up, so a draft is refused.
  • lastUpdated: ISO 8601 with a time zone, for example 2026-11-16T09:00:00Z. It is kept, but the time of a version is the time it was stored.
  • economicOperatorId
  • When given: facilityId (a string) and contentSpecificationIds (a list of strings).

Everything else in the passport is a data element and is stored as sent.

What is not public

EN 18222 carries no access rules of its own, so you list the data elements that are not public in one extra member, x-backup. It is not a data element and is never published.

"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }

EN 18221 4.3 asks the copy to keep the access restrictions of the original passport, and this list is how the copy knows them. Without it we show no product data from that version publicly rather than guess. In an update, a member you leave out stays as it was.

Attached documents (EN 18221 4.4): how to send their files is not described here yet. Coming

Sending a call again

A create or an update may carry an Idempotency-Key header of 1 to 200 printable characters. The same key with the same request gets the first answer again, with Idempotent-Replay: true, and nothing new is stored. The same key with another request is refused.

An example

POST /api/v1/dpps HTTP/1.1
Host: dpp-backup.com
Authorization: Bearer <credential>
Content-Type: application/json
Idempotency-Key: 2f1f3c9b-create-1

{
  "digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
  "uniqueProductIdentifier": "https://id.example.com/01/09506000134352/21/ABC123",
  "granularity": "item",
  "dppSchemaVersion": "1.0",
  "dppStatus": "active",
  "lastUpdated": "2026-11-16T09:00:00Z",
  "economicOperatorId": "urn:example:operator:4012345000009",
  "x-backup": { "withheldFromPublic": ["supplierPrice"] },
  "productName": "Wool jumper",
  "supplierPrice": "internal"
}
HTTP/1.1 201 Created
Backup-Receipt: eyJ2IjoxLCJrZXlfaWQiOi...

{
  "digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
  "x-backup": {
    "versionNumber": 1,
    "receivedAt": "2026-11-16T09:00:01.482Z",
    "versionId": "0d6e7a52-5b0c-4f7e-9d0e-8a3c1f9b2c44",
    "contentSha256": "3b5d…64 hex digits…9f1c",
    "receipt": "eyJ2IjoxLCJrZXlfaWQiOi..."
  }
}

Reading from the copy

EN 18222 callRequest
ReadDPPById (4.2)GET /api/v1/dpps/{dppId}
ReadDPPByProductId (4.3)GET /api/v1/dppsByProductId/{productId}, a GTIN of 8 to 14 digits or a GS1 Digital Link address
ReadDPPIdsByProductIds (4.5)POST /api/v1/dppsByProductIds with {"productIds": ["09506000134352"]}, at most 1,000 GTINs
ReadDPPVersionByIdAndDate (4.4)GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z

A read answers the newest version, or for a date the version that was current then. Ask for application/json, application/ld+json or text/html in the Accept header (EN 18216 content negotiation). Every answer says that it is the back-up copy, which version it is, and the SHA-256 hash of its content.

The passport's own address works too: /01/{gtin} with the GS1 Digital Link keys after it.

The read calls answer on a domain that is open for reading. A domain is opened when a brand points its passport domain at the copy. Everywhere else, a read answers 404.

Not offered: ReadDataElement and UpdateDataElement (EN 18222 clause 6).

Receipts

Every stored version gets a receipt. It is two parts joined by a dot, each base64url without padding:

base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)

The signature covers the first part exactly as written, so nothing has to be put in order before checking. The JSON holds:

FieldWhat it is
vThe format version, now 1
key_idThe key that signed it
receipt_idThe id of the stored version
senderWho sent the version
dpp_idThe digitalProductPassportId
version_numberThe number of the version, from 1
content_sha256The SHA-256 hash of the content, as hex
received_atWhen the version was stored

The public key

GET /.well-known/backup-receipt-key answers:

{
  "algorithm": "Ed25519",
  "key_id": "…16 hex digits…",
  "public_key_spki_base64": "MCowBQYDK2VwAyEA…",
  "receipt_format": "base64url(JSON) \".\" base64url(signature over the first part as written)"
}

key_id is the first 16 hex digits of the SHA-256 hash of the key in its SPKI form. Check a receipt on the verify page, or with any Ed25519 library.

Error codes

A refused create or update answers with the result object of EN 18222 7.2:

{
  "message": [
    {
      "messageType": "Error",
      "text": "dppStatus is \"draft\". Drafts are not backed up: send the passport when it is published",
      "code": "400",
      "timestamp": "2026-11-16T09:00:01.482Z"
    }
  ]
}
StatusWhen (create and update)
400The body is not a JSON object, a mandatory attribute is missing or wrong, the passport is a draft, the id was changed, or the Idempotency-Key is not valid or was used with another request.
401The credential is wrong or missing.
403The connection is no longer in force.
404An update for a passport that is not held for this connection.
405A delete, or a method that is not allowed on the path.
409A create for a passport that is held already, an update that met another update, or a call whose Idempotency-Key is still running (with Retry-After).
413The body, or the passport after the update, is larger than 1,048,576 bytes.
429Too many calls. Wait for the seconds in Retry-After.
500The passport could not be stored. Send it again; with the same Idempotency-Key nothing is stored twice.

The read calls answer {"error": "…"}:

StatusWhen (reads)
300More than one brand holds a passport at this address. The answer lists them.
400The id, the GTIN or the date is missing or not valid.
404The passport is not held in the copy, or the domain is not open for reading.
405A method that is not allowed on the path.
413More than 1,000 product ids.
429Too many requests. Wait for the seconds in Retry-After.
503Temporarily unavailable. Try again after Retry-After.

Keep a back-up copy of your passports

Create an organisation with your company email. Once it is approved, you connect the platform that holds your passports.

A company email address is required. Our staff review new organisations on working days. The portal is in English.