Skip to main content

Veribl Python SDK

The official Python library for the Veribl API: digital product passports (EN 18222), products, battery units, manuals, articles, registrations, contacts and webhooks.

Requires Python 3.9 or later. The only dependency is httpx.

Install

pip install veribl

Quickstart

Make an API key in Settings › API keys, then set it as VERIBL_API_KEY (or pass it to Veribl("vdpp_...")).

from veribl import Veribl

client = Veribl()  # reads VERIBL_API_KEY

# List products (one page)
page = client.products.list(status="live", limit=20)
for product in page.data:
    print(product["id"], product["name"])

# Read a product's passport through the Passport API (EN 18222), by its GS1 Digital Link
passport = client.dpps.retrieve_by_product_id("https://go.veribl.com/01/04012345678901")
print(passport["dppHeader"])

# Create a product
product = client.products.create({"name": "Trail E-Bike 500", "gtin": "04012345678901"})
print(product["id"])

Responses are plain dicts and lists, as the API sends them. Use the client as a context manager, or call client.close(), to release connections:

with Veribl() as client:
    ...

For an endpoint this SDK version doesn't name yet, use client.request("GET", "/v1/languages").

Pagination

List calls return a Page with .data and .next_cursor. To walk every item across pages:

for product in client.products.list(status="live").auto_paging_iter():
    print(product["name"])

Errors

Every failed call raises a VeriblError (or a subclass) with the HTTP status, the error code and the request id to quote to support@veribl.com.

from veribl import VeriblError, VeriblInvalidRequestError

try:
    client.products.retrieve("missing")
except VeriblInvalidRequestError as e:
    print(e.status, e.code, e.request_id, e.message)  # 404 not_found req_... No product with this id.
except VeriblError as e:
    print("Veribl error", e.status, e.request_id)
Class When
VeriblAuthenticationError 401: key missing, invalid, revoked or expired
VeriblPermissionError 403: the key or plan doesn't allow this
VeriblInvalidRequestError 400, 404, 409, 422: something about the request is wrong
VeriblRateLimitError 429: too many requests
VeriblAPIError 5xx: a failure on Veribl's side
VeriblConnectionError no answer: network failure or timeout
VeriblSignatureVerificationError a webhook signature doesn't match

Network errors, 408, 429 and 5xx are retried automatically (2 times by default, honoring Retry-After, otherwise with exponential backoff). Change it with Veribl(max_retries=5) or per call.

Idempotency

Every write (anything other than GET) is sent with an Idempotency-Key, generated for you and identical across retries, so a retried request is never applied twice. To use your own key, for example one tied to a row in your database:

client.products.create({"name": "Trail E-Bike 500"}, idempotency_key="import-row-8841")

Per-call options

Every method accepts these keyword arguments: idempotency_key, api_version, max_retries, timeout (seconds) and extra_headers.

Test mode

Keys that start with vdpp_test_ reach test data only; vdpp_ keys reach live data.

client = Veribl("vdpp_test_...")
client.test_mode  # True

Webhooks

Verify every delivery with the endpoint secret, using the raw request body exactly as received (before any JSON parsing). A Flask example:

import os
from flask import Flask, request
from veribl import Veribl, VeriblSignatureVerificationError

app = Flask(__name__)

@app.post("/webhooks/veribl")
def veribl_webhook():
    try:
        event = Veribl.webhooks.construct_event(
            request.get_data(),  # raw bytes, not request.json
            request.headers.get("Veribl-Signature"),
            os.environ["VERIBL_WEBHOOK_SECRET"],
        )
    except VeriblSignatureVerificationError:
        return "invalid signature", 400

    if event["event"] == "passport.published":
        print("Published", event["data"])
    return "", 204

Deliveries older than 5 minutes are rejected (tolerance=300). The event id is the same on every retry, so deduplicate on it. In tests, Veribl.webhooks.generate_test_header(body, secret) makes a valid header.

API versions

Pin a dated API version, sent as Veribl-Version, for the whole client or for one call:

client = Veribl(api_version="2026-10-21")
client.products.list(api_version="2026-10-21")

Without it, you get the version your key was made with.

Documentation

Full API reference and guides: https://docs.veribl.com

License

MIT

Metadata

Release files for veribl 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for veribl 0.2.0
File Size Uploaded Provenance Actions
veribl-0.2.0.tar.gz 36.7 kB With provenance Details for veribl-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for veribl 0.2.0
File Interpreter ABI Platform Actions
veribl-0.2.0-py3-none-any.whl Python 3 none any Details for veribl-0.2.0-py3-none-any.whl

Total release size: 73.3 kB

Release files / veribl-0.2.0.tar.gz

Download URL veribl-0.2.0.tar.gz
Size 36.7 kB
Tags Source
SHA-256 checksum
How to use checksums
aeeb78519a86f33a06cfdefbb2f25ec8d7dc0a3ee846f5e3ee2d67a2d772c9df
BLAKE2b-256 checksum
How to use checksums
cde9666321688a3f972306192c5805b0256edd5f977b7ac1a4f34d623a3f9f37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / veribl-0.2.0-py3-none-any.whl

Download URL veribl-0.2.0-py3-none-any.whl
Size 36.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
462a75049d2806533ac86773922032f6218541eddedc3a099dae452d967a8883
BLAKE2b-256 checksum
How to use checksums
3c8cd836a68984db79aee2cc0291f0ed69d1a9a4d0b448a72006c6b52eafa834
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for veribl 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for veribl-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page