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 call | Request | Answer |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps with the whole passport | 201 and the stored version |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} with the parts that changed | 200 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,batchoritem.dppSchemaVersiondppStatus:active,inactive,archivedorinvalid. Only published passports are backed up, so a draft is refused.lastUpdated: ISO 8601 with a time zone, for example2026-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) andcontentSpecificationIds(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 call | Request |
|---|---|
| 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:
| Field | What it is |
|---|---|
v | The format version, now 1 |
key_id | The key that signed it |
receipt_id | The id of the stored version |
sender | Who sent the version |
dpp_id | The digitalProductPassportId |
version_number | The number of the version, from 1 |
content_sha256 | The SHA-256 hash of the content, as hex |
received_at | When 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"
}
]
}
| Status | When (create and update) |
|---|---|
| 400 | The 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. |
| 401 | The credential is wrong or missing. |
| 403 | The connection is no longer in force. |
| 404 | An update for a passport that is not held for this connection. |
| 405 | A delete, or a method that is not allowed on the path. |
| 409 | A 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). |
| 413 | The body, or the passport after the update, is larger than 1,048,576 bytes. |
| 429 | Too many calls. Wait for the seconds in Retry-After. |
| 500 | The passport could not be stored. Send it again; with the same Idempotency-Key nothing is stored twice. |
The read calls answer {"error": "…"}:
| Status | When (reads) |
|---|---|
| 300 | More than one brand holds a passport at this address. The answer lists them. |
| 400 | The id, the GTIN or the date is missing or not valid. |
| 404 | The passport is not held in the copy, or the domain is not open for reading. |
| 405 | A method that is not allowed on the path. |
| 413 | More than 1,000 product ids. |
| 429 | Too many requests. Wait for the seconds in Retry-After. |
| 503 | Temporarily 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.