Quick Start

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://production-api.puppetvendors.com/authenticate \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "vk_live_YOUR_API_KEY"}'

import requests

resp = requests.post(
    "https://production-api.puppetvendors.com/authenticate",
    json={"apiKey": "vk_live_YOUR_API_KEY"}
)
token = resp.json()["data"]["token"]

const resp = await fetch("https://production-api.puppetvendors.com/authenticate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ apiKey: "vk_live_YOUR_API_KEY" })
});
const { data } = await resp.json();
const token = data.token;

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://production-api.puppetvendors.com/orders?first=5" \
  -H "x-access-token: YOUR_TOKEN"

resp = requests.get(
    "https://production-api.puppetvendors.com/orders",
    params={"first": 5},
    headers={"x-access-token": token}
)
orders = resp.json()["data"]["items"]
for order in orders:
    print(f"#{order['orderNumber']} — ${order['totalSales']}")

const resp = await fetch("https://production-api.puppetvendors.com/orders?first=5", {
  headers: { "x-access-token": token }
});
const { data } = await resp.json();
data.items.forEach(order => console.log(`#${order.orderNumber} — $${order.totalSales}`));

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://production-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://production-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://production-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://production-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://production-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://production-api.puppetvendors.com/orders?first=20" \
  -H "x-access-token: YOUR_TOKEN"

# Page 2 (use endCursor from previous response)
curl "https://production-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://production-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://production-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://production-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://production-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:

Status	Meaning	What to Do
400	Bad request (validation error)	Check the `details` field for which parameter failed
401	Token expired or missing	Re-authenticate with `POST /authenticate`
403	Insufficient scope	Your API key doesn’t have the required scope
404	Resource not found	Verify the ID exists and belongs to your vendor account
429	Rate limited	Wait and retry — limit is 100 requests/minute
500	Server error	Retry 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 /resources/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

Getting Started

Authentication

Vendor Portal Auth

Orders

Products

Fulfillments

Fulfillment Events

Documents

Payouts

Customers

Discounts

Shipping Operations

Vendor Profile

Account Settings

Shipping Settings

Team Members

Users

Integrations

Overview

Prerequisites

Step 1: Authenticate

Step 2: List Your Orders

Step 3: Create a Product

Step 4: Create a Fulfillment

Step 5: Check Your Payout Summary

Common Patterns

Filtering

Exporting to CSV

Generating Documents

Postman / Insomnia

Download Postman Collection

Error Handling

For AI Agents

​Overview

​Prerequisites

​Step 1: Authenticate

​Step 2: List Your Orders

​Step 3: Create a Product

​Step 4: Create a Fulfillment

​Step 5: Check Your Payout Summary

​Common Patterns

​Filtering

​Pagination

​Exporting to CSV

​Generating Documents

​Postman / Insomnia

Download Postman Collection

​Error Handling

​For AI Agents

Overview

Prerequisites

Step 1: Authenticate

Step 2: List Your Orders

Step 3: Create a Product

Step 4: Create a Fulfillment

Step 5: Check Your Payout Summary

Common Patterns

Filtering

Pagination

Exporting to CSV

Generating Documents

Postman / Insomnia

Error Handling

For AI Agents