> ## 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 Merchant API Introduction

> Overview of the PuppetVendors V2 Merchant 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 Merchant API gives merchants programmatic, shop-wide access to administer their marketplace — creating and managing vendors, managing users, and adjusting vendor payouts.

Unlike vendor keys (`vk_`), which are restricted to a single vendor's data, a merchant key (`mk_`) operates at the shop level across all vendors.

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

<Info>
  **For AI agents and tooling:** [OpenAPI 3.1 spec](https://production-api.puppetvendors.com/resources/openapi-merchant.json)
</Info>

## Getting Started

1. **Get your merchant API key** — Create one in the PuppetVendors admin under **Settings → API Access** (prefixed `mk_live_` or `mk_test_`). The key is revealed once at creation, so store it securely.
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/merchant/authentication) for details.

## Merchant Resources

<CardGroup cols={2}>
  <Card title="Vendors" icon="store" href="/api-reference/v2/merchant/endpoint/list-vendors">
    Create, update, and manage vendors, their profiles, and addresses
  </Card>

  <Card title="Users" icon="users" href="/api-reference/v2/merchant/endpoint/list-users">
    Manage vendor user accounts
  </Card>

  <Card title="Payout Adjustments" icon="money-bill-wave" href="/api-reference/v2/merchant/endpoint/list-payout-adjustments">
    Add manual additions or deductions to vendor payouts
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/v2/merchant/endpoint/authenticate">
    Mint, verify, and refresh API tokens
  </Card>
</CardGroup>

## Scope of a Merchant Key

A merchant token carries the `admin:users`, `admin:vendors`, and `admin:payouts` permissions, which cover the endpoints in this tab:

| Permission      | Endpoints                                       |
| --------------- | ----------------------------------------------- |
| `admin:vendors` | `/vendors` and vendor profile/address endpoints |
| `admin:users`   | `/users` endpoints                              |
| `admin:payouts` | `/payouts/adjustments` endpoints                |

Everything else in the V2 API — orders, products, payouts, fulfillments, documents — stays on the V1 API token and is refused with HTTP 403 when called with a merchant token.

## Key Lifecycle

* **Created** in **Settings → API Access**; each key is named per integration and independently rotatable and revocable
* **Revealed once** — the full key is shown only at creation
* **Rotation is an overlap, not a cutover** — a rotated key keeps working for a 24-hour grace window while you roll out the new one
* **Revoking** a key refuses the next request made with any token minted from it

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