Skip to main content
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 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

  1. Get your merchant API key — Create one in the PuppetVendors admin under Settings → API Access (prefixed mk_live_ or mk_test_). The key is revealed once at creation, so store it securely.
  2. Authenticate — Exchange your key for a JWT token via POST /authenticate
  3. Make requests — Pass the token in the x-access-token header
See the Authentication guide for details.

​
Merchant Resources

Vendors

Create, update, and manage vendors, their profiles, and addresses

Users

Manage vendor user accounts

Payout Adjustments

Add manual additions or deductions to vendor payouts

Authentication

Mint, verify, and refresh API tokens

​
Scope of a Merchant Key

A merchant token carries the admin:users, admin:vendors, and admin:payouts permissions, which cover the endpoints in this tab: Everything else in the V2 API — orders, products, payouts, fulfillments, documents — stays on the V1 API token and is 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 standard RateLimit-* headers on every response. On HTTP 429, implement exponential backoff before retrying.

​
Need Help?

Contact support@puppetvendors.com for API access or questions.