Skip to main content

​
Overview

This guide walks you through making your first API calls. By the end, you’ll have listed your orders and created a product.

​
Prerequisites

  • A vendor API key (starts with vk_) — get one from your merchant or create one in Settings > API Keys
  • A tool to make HTTP requests: curl, Postman, Insomnia, or any programming language

​
Step 1: Authenticate

Exchange your API key for a JWT token: 
curl -X POST https://staging-api.puppetvendors.com/authenticate \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "vk_live_YOUR_API_KEY"}'
Response: 
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 86400,
    "scope": "vendor",
    "permissions": ["orders:read", "products:read", "products:write"],
    "shopDomain": "my-store.myshopify.com",
    "mode": "live"
  }
}
Save the token value — you’ll use it for all subsequent requests. It expires in 24 hours. The permissions array shows which scopes your key has.

​
Step 2: List Your Orders

curl "https://staging-api.puppetvendors.com/orders?first=5" \
  -H "x-access-token: YOUR_TOKEN"
Response: 
{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "665a1b2c3d4e5f6a7b8c9d0e",
        "orderNumber": 1042,
        "orderName": "#1042",
        "totalSales": 149.99,
        "status": "fulfilled",
        "createdAt": "2026-05-15T10:30:00Z"
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "endCursor": "eyJpZCI6IjY2NWExYjJj..."
    },
    "totalCount": 156
  }
}

​
Step 3: Create a Product

curl -X POST https://staging-api.puppetvendors.com/products \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_TOKEN" \
  -d '{
    "title": "Classic Cotton T-Shirt",
    "descriptionHtml": "<p>Soft, breathable cotton tee.</p>",
    "productType": "Apparel",
    "tags": ["cotton", "t-shirt", "summer"],
    "status": "DRAFT",
    "variants": [
      {
        "title": "Small / Blue",
        "price": "29.99",
        "sku": "TEE-BLU-S",
        "inventoryQuantity": 50,
        "weight": 0.3,
        "weightUnit": "KILOGRAMS"
      },
      {
        "title": "Medium / Blue",
        "price": "29.99",
        "sku": "TEE-BLU-M",
        "inventoryQuantity": 75,
        "weight": 0.35,
        "weightUnit": "KILOGRAMS"
      }
    ],
    "options": [
      {"name": "Size", "values": ["Small", "Medium"]},
      {"name": "Color", "values": ["Blue"]}
    ]
  }'

​
Step 4: Create a Fulfillment

Once an order is ready to ship: 
curl -X POST https://staging-api.puppetvendors.com/fulfillments \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_TOKEN" \
  -d '{
    "lineItemIds": ["665a1b2c3d4e5f6a7b8c9d0e"],
    "trackingNumber": "1Z999AA10123456784",
    "shippingCarrier": "UPS",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "notifyCustomer": true
  }'

​
Step 5: Check Your Payout Summary

curl "https://staging-api.puppetvendors.com/payouts/summary" \
  -H "x-access-token: YOUR_TOKEN"
Response: 
{
  "success": true,
  "data": {
    "totalReceived": 12500.00,
    "totalPending": 3200.00,
    "totalScheduled": 1500.00,
    "currency": "USD",
    "previousPayout": {
      "amount": 5000.00,
      "status": "paid",
      "date": "2026-05-01T00:00:00Z"
    },
    "nextPayout": {
      "amount": 1500.00,
      "estimatedDate": "2026-06-01T00:00:00Z",
      "type": "automated"
    }
  }
}

​
Common Patterns

​
Filtering

Most list endpoints support filters via query parameters: 
# Orders from the last 7 days
curl "https://staging-api.puppetvendors.com/orders?first=20&startDate=2026-05-12T00:00:00Z&status=pending" \
  -H "x-access-token: YOUR_TOKEN"

# Products that are out of stock
curl "https://staging-api.puppetvendors.com/products?first=50&inventoryStatus=outOfStock" \
  -H "x-access-token: YOUR_TOKEN"

​
Pagination

All list endpoints use cursor-based pagination. See the Pagination guide for details. 
# Page 1
curl "https://staging-api.puppetvendors.com/orders?first=20" \
  -H "x-access-token: YOUR_TOKEN"

# Page 2 (use endCursor from previous response)
curl "https://staging-api.puppetvendors.com/orders?first=20&after=eyJpZCI6..." \
  -H "x-access-token: YOUR_TOKEN"

​
Exporting to CSV

Many endpoints have an /export variant that returns a CSV file: 
# Download orders as CSV
curl "https://staging-api.puppetvendors.com/orders/export?startDate=2026-05-01T00:00:00Z" \
  -H "x-access-token: YOUR_TOKEN" \
  -o orders.csv
Export responses can be:
  • 200 — CSV data streamed directly
  • 202 — Export queued (large datasets), check back later
  • 204 — No data matches your filters

​
Generating Documents

Each document type has its own endpoint — simple and clear: 
# Generate an invoice
curl -X POST https://staging-api.puppetvendors.com/documents/invoice \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_TOKEN" \
  -d '{"orderIds": [1042, 1043]}'

# Generate a packing slip
curl -X POST https://staging-api.puppetvendors.com/documents/packing-slip \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_TOKEN" \
  -d '{"orderIds": [1042]}'

# Generate a shipping label
curl -X POST https://staging-api.puppetvendors.com/documents/shipping-label \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_TOKEN" \
  -d '{"orderIds": [1042]}'
All document endpoints return a temporary URL: 
{
  "success": true,
  "data": {
    "url": "https://s3.amazonaws.com/...",
    "expiresAt": "2026-05-19T12:00:00Z"
  }
}

​
Postman / Insomnia

Download our ready-to-import collection:

Download Postman Collection

Import into Postman or Insomnia. Set your api_key variable and hit Authenticate — all other requests auto-use the token.

​
Error Handling

All errors follow the same format: 
{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE",
    "details": {}
  }
}
Common HTTP status codes:
StatusMeaningWhat to Do
400Bad request (validation error)Check the details field for which parameter failed
401Token expired or missingRe-authenticate with POST /authenticate
403Insufficient scopeYour API key doesn’t have the required scope
404Resource not foundVerify the ID exists and belongs to your vendor account
429Rate limitedWait and retry — limit is 100 requests/minute
500Server errorRetry after a brief delay, contact support if persistent

​
For AI Agents

This API is designed to be AI-agent friendly:
  • OpenAPI 3.1 spec available at /docs/public/openapi.yaml — import it to understand all endpoints, schemas, and constraints
  • Consistent response format — every response has {success, data, error?}
  • Cursor-based pagination — no page drift when data changes
  • Scoped API keys — create keys with minimal permissions for your agent
  • Postman collection — auto-generates working requests for every endpoint