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

# V2 Vendor API Introduction

> Overview of the PuppetVendors V2 Vendor API (Alpha)

<Note>
  **V2 Preview** — The V2 API is actively being developed. We aim for stability but breaking changes may occasionally occur.
</Note>

## Overview

The PuppetVendors V2 Vendor API gives vendors direct, secure access to their own data — orders, products, fulfillments, payouts, and more — without going through the merchant.

Vendor-scoped tokens are automatically restricted to the authenticated vendor's data. There is no way for a vendor token to access another vendor's resources.

**Base URL:** `https://staging-api.puppetvendors.com`

<Info>
  **For AI agents and tooling:** [OpenAPI 3.1 spec](https://staging-api.puppetvendors.com/docs/public/openapi.yaml) | [Postman Collection](https://staging-api.puppetvendors.com/docs/public/PuppetVendors_V2_Vendor_API.postman_collection.json)
</Info>

## Getting Started

1. **Get your vendor API key** — Create one in the vendor portal or ask your merchant for a key (prefixed `vk_`)
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](/api-reference/v2/vendor/authentication) and [API Keys & Scopes](/api-reference/v2/vendor/api-keys-scopes) for details.

## Vendor Resources

<CardGroup cols={2}>
  <Card title="Orders" icon="cart-shopping" href="/api-reference/v2/endpoint/vendor-list-orders">
    View, export, and track your orders
  </Card>

  <Card title="Products" icon="box" href="/api-reference/v2/endpoint/vendor-list-products">
    Create, update, and manage your products
  </Card>

  <Card title="Fulfillments" icon="truck" href="/api-reference/v2/endpoint/vendor-list-fulfillments">
    Create, update, and track fulfillments
  </Card>

  <Card title="Documents" icon="file-pdf" href="/api-reference/v2/vendor/endpoint/generate-invoice">
    Generate invoices, packing slips, and shipping labels
  </Card>

  <Card title="Payouts" icon="money-bill-wave" href="/api-reference/v2/endpoint/vendor-list-payouts">
    Track payouts, transactions, and pending balances
  </Card>

  <Card title="Shipping" icon="shipping-fast" href="/api-reference/v2/vendor/endpoint/get-shipping-rates-op">
    Get rates, purchase labels, manage dimensions
  </Card>

  <Card title="Customers" icon="users" href="/api-reference/v2/endpoint/vendor-list-customers">
    View customers who purchased your products
  </Card>

  <Card title="Discounts" icon="tag" href="/api-reference/v2/endpoint/vendor-list-discounts">
    Manage your discount codes
  </Card>

  <Card title="Integrations" icon="plug" href="/api-reference/v2/vendor/endpoint/list-integrations">
    Connect Shippo, ShipStation, PayPal, and Stripe
  </Card>

  <Card title="Profile & Settings" icon="gear" href="/api-reference/v2/vendor/endpoint/get-my-profile">
    Update your profile, address, and account settings
  </Card>
</CardGroup>

## Unscoped Endpoints

Some endpoints work with any valid vendor token — no specific scope required on your API key:

**Discounts**, **Profile**, **Settings** (account, shipping, team), **Integrations** (Shippo, ShipStation, PayPal, Stripe), and **Documents** (invoices, packing slips, shipping labels).

See [API Keys & Scopes](/api-reference/v2/vendor/api-keys-scopes) for the full breakdown.

## 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 agent 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](mailto:support@puppetvendors.com) for API access or questions.