> ## Documentation Index
> Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with the PuppetVendors Vendor API in 5 minutes

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://staging-api.puppetvendors.com/authenticate \
    -H "Content-Type: application/json" \
    -d '{"apiKey": "vk_live_YOUR_API_KEY"}'
  ```

  ```python Python theme={null}
  import requests

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

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://staging-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;
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://staging-api.puppetvendors.com/orders?first=5" \
    -H "x-access-token: YOUR_TOKEN"
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://staging-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']}")
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://staging-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}`));
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl "https://staging-api.puppetvendors.com/payouts/summary" \
  -H "x-access-token: YOUR_TOKEN"
```

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
# 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](/api-reference/v2/vendor/pagination) for details.

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://s3.amazonaws.com/...",
    "expiresAt": "2026-05-19T12:00:00Z"
  }
}
```

## Postman / Insomnia

Download our ready-to-import collection:

<Card title="Download Postman Collection" icon="download" href="https://staging-api.puppetvendors.com/docs/public/PuppetVendors_V2_Vendor_API.postman_collection.json">
  Import into Postman or Insomnia. Set your `api_key` variable and hit Authenticate — all other requests auto-use the token.
</Card>

## Error Handling

All errors follow the same format:

```json theme={null}
{
  "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 [`/docs/public/openapi.yaml`](https://staging-api.puppetvendors.com/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