Skip to main content
V2 Alpha — This authentication flow is part of the V2 API preview. Breaking changes may occur.

​
Overview

All V2 Merchant API endpoints require a JWT token passed via the x-access-token header. You obtain this token by exchanging your merchant API key at POST /v2/authenticate.

​
Merchant API Key

Your merchant (shop) API key is found in Settings > Information in the PuppetVendors dashboard.
Key TypePrefixToken ScopeWhere to Find
Merchant key(none)merchant — full accessSettings > Information in the PuppetVendors dashboard

​
Authenticating

Exchange your merchant API key for a JWT token: 
curl -X POST https://api.puppetvendors.com/v2/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_MERCHANT_API_KEY"
  }'

​
Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "scope": "merchant",
    "shopDomain": "my-store.myshopify.com"
  }
}

​
Using the Token

Include the token in all subsequent requests via the x-access-token header: 
curl -X GET "https://api.puppetvendors.com/v2/orders?first=10" \
  -H "x-access-token: YOUR_JWT_TOKEN"

​
Token Expiry & Refresh

Tokens expire after 24 hours (86400 seconds). Use POST /v2/refresh-token with a valid (non-expired) token to get a new one without re-authenticating: 
curl -X POST https://api.puppetvendors.com/v2/refresh-token \
  -H "x-access-token: YOUR_CURRENT_TOKEN"

​
Filtering by Vendor

Merchant tokens have access to all vendors. You can optionally filter by vendorId query parameter to see a specific vendor’s data. Some endpoints (like fulfillments and payouts) require the vendorId parameter for merchant tokens.