V2 Preview — The V2 API is actively being developed. We aim for stability but breaking changes may occasionally occur.
Overview
The PuppetVendors V2 Merchant API gives merchants programmatic, shop-wide access to administer their marketplace — creating and managing vendors, managing every vendor’s products, managing users, and adjusting vendor payouts. Unlike vendor keys (vk_), which are restricted to a single vendor’s data, a merchant key (mk_) operates at the shop level across all vendors.
Base URL: https://production-api.puppetvendors.com
For AI agents and tooling: OpenAPI 3.1 spec
Getting Started
- Get your merchant API key — Create one in the PuppetVendors admin under Settings → API Access (prefixed
mk_live_ormk_test_). The key is revealed once at creation, so store it securely. - Authenticate — Exchange your key for a JWT token via
POST /authenticate - Make requests — Pass the token in the
x-access-tokenheader
Merchant Resources
Vendors
Create, update, and manage vendors, their profiles, and addresses
Users
Manage vendor user accounts
Products
Manage every vendor’s products, and approve or reject pending ones
Payout Adjustments
Add manual additions or deductions to vendor payouts
Authentication
Mint, verify, and refresh API tokens
Scope of a Merchant Key
A merchant key carries a read and a write permission for each resource. Each endpoint page names the permission it needs:
Merchant keys use the same
/products paths as the vendor API and see every vendor’s products. Add ?vendorId= to narrow a request to one vendor.
Orders, customers, fulfillments and documents stay on the V1 API token and are refused with HTTP 403 when called with a merchant token.
Key Lifecycle
- Created in Settings → API Access; each key is named per integration and independently rotatable and revocable
- Revealed once — the full key is shown only at creation
- Rotation is an overlap, not a cutover — a rotated key keeps working for a 24-hour grace window while you roll out the new one
- Revoking a key refuses the next request made with any token minted from it
Rate Limits
The API is rate-limited to 100 requests per minute per IP address. The limit is per IP, not per API key — if your integration runs in a shared environment (Lambda, Vercel, CI), all consumers on that IP share the 100/min budget. The API returns standardRateLimit-* headers on every response. On HTTP 429, implement exponential backoff before retrying.