REST API v1 · Subscriber API (Professional+) · Integration API for builders

Build with Zentria Flow

Programmatic access to supply chain intelligence, landed cost calculation, HS code lookup, and order data over a REST API with JSON responses.

Authentication

All API requests require a valid API key. Generate one in Settings → API Keys. Pass it via either header:

X-API-Key header

X-API-Key: zf_live_your_key_here

Authorization: Bearer

Authorization: Bearer zf_live_your_key_here
Base URL
https://api.zentriaflow.com/api/v1/

Machine-readable description: OpenAPI spec (OpenAPI 3.1, JSON). It covers the tariff and landed-cost endpoints and the free tariff endpoints that need no key, with request and response schemas, plan quotas and error codes. Import it into an API client or a code generator.

API Reference

All endpoints return JSON. Errors follow { detail: string } format.

GET/api/v1/me

Returns account info, plan, and scopes for the authenticated API key.

Response

{
  "user_id": "usr_abc123",
  "email": "[email protected]",
  "plan": "professional",
  "api_key_name": "My Claude Agent",
  "scopes": ["read", "write"]
}

Example

curl https://api.zentriaflow.com/api/v1/me \
  -H "X-API-Key: zf_live_your_key"

Watchlist events (webhooks)

Two events exist today, both about your Watchlist. On the Scale API plan and Enterprise they are pushed to your own https URL, signed, when the Watchlist re-price finds a tariff change on a product you watch. Register the URL with POST /api/v1/hooks. On every plan with Watchlist access (Scale API and higher, Professional, Enterprise) you can also poll GET /api/v1/watchlist/changes, where every change has a stable id. Unsigned hooks to a hooks.zapier.com URL are for the Zapier integration, which is coming soon and not yet published.

watch.tariff_changed

A tariff change moved the cost of a watched product

watch.created

A product was added to the Watchlist

Each delivery is a JSON POST with the keys of the matching list endpoint and the headers X-Zentria-Event, X-Zentria-Hook-Id, X-Zentria-Delivery (the same on every retry of one event, so you can ignore a repeat) and X-Zentria-Signature.

Verify the signature

The header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw request body> keyed with the signing secret you received when you created the hook. Compute it over the raw bytes, before parsing the JSON, compare in constant time, and refuse a timestamp older than five minutes.

import hashlib, hmac, time

def verify(secret: str, signature_header: str, raw_body: bytes, tolerance_s: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, v1 = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > tolerance_s:
        return False                      # too old: possibly a replay
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

# secret = the signing_secret from POST /api/v1/hooks
# signature_header = the X-Zentria-Signature request header

Delivery rules

  • Answer with any 2xx status. Each attempt has a 5-second timeout, the response body is ignored and redirects are not followed.
  • A delivery that fails is tried again, up to 3 attempts in all: not sooner than 1 minute after the first, and not sooner than 5 minutes after the second.
  • Changes are found by the Watchlist re-price, which runs about every 6 hours, and retries go out with the next activity on our servers, so a delivery or a retry can arrive later than those times. Delivery time is not guaranteed; GET /api/v1/watchlist/changes always has the full list.
  • After 5 failed attempts in a row the hook is switched off and listed with disabled_at. A successful POST /api/v1/hooks/{id}/test switches it back on.
  • A 410 answer removes the hook. Revoking the API key that created a hook removes it too.
  • The URL must be https on port 443 with a public hostname. Private, loopback, link-local and reserved addresses (IPv4 and IPv6) are refused when you register and again at every delivery.

Subscriber API Limits

Your Zentria plan

API access is included in the Professional and Enterprise subscriptions. Keys are scoped to your own account data.

PlanAPI AccessReq / minReq / dayKey prefix
FreeNo access———
GrowthNo access———
ProfessionalEnabled60500zf_live_
EnterpriseEnabled3005,000zf_live_

Exceeded limits return 429 Too Many Requests with Retry-After and X-RateLimit-Reset headers.

Integration API

For builders

Building a logistics platform, freight quoting tool, procurement system, or AI agent that needs duty rates and landed cost? The API plans below are sold separately from the web app subscriptions, with monthly call quotas instead of daily ones.

API-plan keys are created the same way, at Settings → API Keys.

Sandbox

Free

📦 100 calls / mo

⚡ 5 rpm

🔒 No SLA

Testing & integration only

Get sandbox key

Growth API

$199/ month

📦 20,000 calls / mo

⚡ 30 rpm

🔒 Email support

Early-stage products

Start Growth API

Scale API

$599/ month

📦 50,000 calls / mo

⚡ 200 rpm

🔒 Priority email support

Production platforms

Start Scale API

Enterprise

Custom

📦 Unlimited

⚡ Unlimited

🔒 SLA agreed in contract

Dedicated support & contract

Contact us
💸

Revenue share for integration partners

If your product sends us customers (your users sign up for their own Zentria Flow accounts after using your integration), you earn 20% of their subscription payments for their first 12 months, on the same terms as the partner program.

See the partner program →

Integrations

What exists today, and what does not yet. Anything not listed here reaches Zentria Flow by calling the REST API.

REST API

Available

Landed cost, HS code lookup and US tariff layers over HTTPS with an API key. JSON in, JSON out.

API reference →

OpenAPI spec

Available

An OpenAPI 3.1 description of the tariff and landed-cost endpoints, for API clients and code generators.

openapi.json →

Free tariff endpoints

Available, no key

US tariff layers by HTS code and origin, and HTSUS line search. Tariff checks: 60 an hour per IP address. HTS search: 600 an hour. They are in the OpenAPI spec under "Free tools".

Try the checker →

MCP server for AI assistants

Available on GitHub

A Model Context Protocol server for Claude, Cursor, VS Code and other MCP clients: US tariff layers by HTS code and origin, origin comparison, HTSUS search, and landed cost with an API key. Install with: npx -y github:orhansavash/zentria-flow-mcp. Not on npm or in the official MCP registry yet.

zentria-flow-mcp on GitHub →

WooCommerce plugin

Listed on WordPress.org

Landed cost and duty estimates inside a WooCommerce store.

WooCommerce plugin →

Zapier

In development, not on Zapier yet

Landed cost, tariff lookups and Watchlist alerts in Zaps. It is not available on Zapier yet.

Shopify

Not on the Shopify App Store yet

The Shopify app is not on the Shopify App Store yet.

Shopify page →

Ready to build?

Subscriber? Generate an API key from your dashboard in seconds.
Builder? Start with the free Sandbox (100 calls a month) or ask us about an API plan.