Documentation Index
Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Vendor API keys let you authenticate with the PuppetVendors API programmatically. Each key is scoped to a single vendor account and can be restricted to specific permissions.
Key Prefixes
| Prefix | Mode | Description |
|---|
vk_live | Live | Full access to real data |
vk_test | Test | For development and testing |
Available Scopes
Every API key must have at least one scope. Each scope grants access to a specific set of endpoints.
| Scope | Access | Endpoints |
|---|
orders:read | Read orders, counts, timeline | GET /orders, GET /orders/:id, GET /orders/counts, GET /orders/:id/timeline |
orders:write | Add order timeline comments | POST /orders/:id/timeline |
products:read | Read products, counts | GET /products, GET /products/:id, GET /products/counts |
products:write | Create, update, delete products, manage inventory and media | POST /products, PUT /products/:id, DELETE /products/:id, PATCH /products/:id/status, PATCH /products/:id/inventory, POST /products/media |
fulfillments:read | Read fulfillments, counts, stats, events | GET /fulfillments, GET /fulfillments/counts, GET /fulfillments/stats, GET /fulfillments/events/:lineItemId |
fulfillments:write | Create and update fulfillments, manage events | POST /fulfillments, PUT /fulfillments/:id, POST /fulfillments/events/:lineItemId, POST /fulfillments/events/bulk |
payouts:read | Read payouts, transactions, pending items, summaries | GET /payouts, GET /payouts/:id, GET /payouts/summary, GET /payouts/transactions, GET /payouts/pending |
customers:read | Read customer list | GET /customers |
Unscoped Endpoints
These endpoints work with any valid vendor token — no specific scope required on your API key:
| Group | Endpoints |
|---|
| Discounts | List, create, update, delete discounts |
| Profile | GET/PUT /vendors/me/profile, GET/PUT /vendors/me/address |
| Settings | Account, profile settings, shipping rates, warehouses, team members |
| Integrations | Shippo, ShipStation, PayPal, Stripe configuration |
| Documents | Invoice, packing slip, shipping label generation |
| Shop | Feature flags and product configuration |
How Scopes Work
When you create an API key, you choose which scopes to include. The API rejects requests that require a scope your key doesn’t have with 403 Forbidden.
Read vs Write
:read scopes grant access to GET endpoints — listing, viewing, and exporting data:write scopes grant access to POST, PUT, PATCH, and DELETE endpoints — creating, updating, and deleting data
Write scopes do not automatically include read access. If you need both, add both scopes (e.g., products:read and products:write).
Managing API Keys
| Action | Endpoint | Description |
|---|
| List keys | GET /settings/public-api/keys | See all your API keys (tokens are masked) |
| Create key | POST /settings/public-api/keys | Create a new key — token shown once |
| Rotate key | POST /settings/public-api/keys/:keyId/rotate | Generate a new token, old one is invalidated |
| Delete key | DELETE /settings/public-api/keys/:keyId | Permanently revoke a key |
When you create or rotate a key, the plaintext token is returned exactly once. Store it securely — you cannot retrieve it later.
Quick Start Example
# 1. Authenticate with your vendor API key
curl -X POST https://staging-api.puppetvendors.com/authenticate \
-H "Content-Type: application/json" \
-d '{"apiKey": "vk_live_abc123..."}'
# Response: {"success": true, "data": {"token": "eyJ...", "expiresIn": 86400}}
# 2. Use the JWT token for subsequent requests
curl -X GET "https://staging-api.puppetvendors.com/orders?first=10" \
-H "x-access-token: eyJ..."
