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 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

  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

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 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.