Getting Started with Protect+

Welcome to the Protect+ public API. This hub introduces what you can do with the API, how authentication works, and points you at the right deep-dive guide for whatever you're building.

If you'd rather just plug the docs into your AI tool and ask questions — skip ahead to the Use with AI assistants section.

What you can do with the Protect+ API

Protect+ exposes a small, focused API surface — not a kitchen sink. The five things you'll typically wire up:

Quick start (5 minutes)

1. Get an API key

In the Protect+ merchant dashboard:

1. Settings → API Keys
2. Click Generate API Key
3. Copy the value — it's shown exactly once, then masked
4. Store it in your secret manager (1Password, AWS / GCP Secrets Manager, GitHub Actions secrets — never in a repo)

2. Exchange the key for a JWT

curl -X POST https://api.protectplus.io/auth/v1/token \
  -H "X-API-Key: $PPLUS_API_KEY" \
  -H "X-Shop-Domain: mystore.myshopify.com"

Response (truncated):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

JWTs are valid for 60 minutes. Cache them in-process — don't mint a fresh JWT per request (the token endpoint has a tighter rate limit than the data endpoints). Full refresh patterns in the API keys & auth guide.

3. Make your first call

curl https://api.protectplus.io/orders \
  -H "Authorization: Bearer $JWT"

Every successful response uses the same envelope:

{
  "success": true,
  "data": { "...": "..." },
  "requestId": "11af4994-c2ff-48bd-bc03-c3a0ba054af3",
  "traceId":   "830f07a5-dae0-4f43-8f96-843996fc5fa1"
}

Always log the requestId — when you contact support, sending us this value lets us pull the exact request from our trace store.

4. Push a shipment

curl -X POST https://api.protectplus.io/shipments \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "order_number": "ORD-12345",
    "customer_email": "[email protected]"
  }'

The endpoint is idempotent on (store, tracking_number) — replay the same call and you'll get a 200 instead of a duplicate. Full guidance, field rules, and update / read endpoints are in the Tracking integration guide.

5. Configure outbound webhooks

In Tracking → Settings → Integration:

1. Save a HTTPS URL (no plain HTTP — we sign over the wire)
2. Click Generate secret and copy the value
3. Click Send test delivery to smoke-test your receiver
4. Toggle Enable when you're ready to receive live events

Protect+ will POST canonical tracking events (shipment_created, shipped, out_for_delivery, delivered, exception) signed with X-PPLUS-Signature: sha256=<hex>. Verifier snippets in Node + Python plus the retry policy are in the Outbound webhooks guide.

Deep-dive guides

For each integration topic we have a focused tutorial-style guide. Read the one that matches what you're building:

API reference

For the full machine-readable contract — every endpoint, every parameter, every response schema, with a built-in "Try it" runner — see the API Reference.

Authentication, rate limits, and errors at a glance

• Auth model: API key → JWT (60-minute lifetime). Send the JWT as Authorization: Bearer <jwt> on every endpoint other than /auth/v1/token.
• Rate limits:
  • POST /auth/v1/token — 20 / 15 min, per API key (cache the JWT!)
  • POST /shipments, PATCH /shipments — 600 / min, per store
  • All other endpoints — 1,000 / hour, per merchant
  • 429 responses carry a Retry-After header in seconds.
• Errors: every error response is RFC 7807 (application/problem+json):
  JSON

  {
    "type":      "https://api.protectplus.io/errors/unauthorized",
    "title":     "Unauthorized",
    "status":    401,
    "detail":    "Token expired",
    "instance":  "/orders",
    "requestId": "11af4994-c2ff-48bd-bc03-c3a0ba054af3"
  }

• Versioning: the current production version is v1 under https://api.protectplus.io. Breaking changes go under a new version path; existing endpoints stay frozen.

Use with AI assistants

This documentation is AI-ready. If you're integrating with the help of an LLM-powered tool (Cursor, Claude Desktop, ChatGPT, Copilot Workspace, etc.), you have two zero-config options:

Option 1 — MCP server (real-time, structured)

The full Protect+ docs (every guide above + every API reference page) are exposed as a Model Context Protocol server at:

https://docs.protectplus.io/mcp

Add it to any MCP-compatible client and your assistant gets live, structured access to the API contract — endpoints, schemas, response codes, and these guides — and can answer questions like "How do I update only the ETA on an existing shipment?" or "Show me the JSON shape of an outbound webhook delivery" without you copy-pasting docs into the prompt.

Option 2 — llms.txt (LLM-friendly index)

For tools that don't speak MCP yet, every page is also exposed as plain markdown via the standard llms.txt convention:

https://docs.protectplus.io/llms.txt

Drop that URL into your LLM's context (or have it crawl the listed .md links) and it'll have the entire API surface to reason over.

Need help?

When you contact support, always include the requestId from the response envelope — it lets us pull the exact request from our trace store and answer in minutes instead of hours.