fanvault-shop Orders API
The Orders API from fanvault-shop — 4 operation(s) for orders.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fanvault-shop:fanvault-shop-orders-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fanvault Orders API
version: 1.0.0
description: Programmatic control of a Fanvault creator storefront. Every path below is one tool from the shared registry, reachable over plain HTTP; the same registry is served as MCP over Streamable HTTP at the endpoint in the x-mcp block, and drives the `fanvault` CLI. All money values are integer cents.
servers:
- url: https://fanvault.shop
security:
- bearerAuth: []
tags:
- name: Orders
paths:
/api/v1/tools/generate_shipping_label:
post:
operationId: generate_shipping_label
summary: Generate shipping label
description: 'Buys a Shippo shipping label for a PAID order and returns the label PDF URL plus tracking. SPENDS REAL MONEY and cannot be undone. REQUIRES the payments scope and the confirmation_token from get_label_quote for this exact order (valid 10 minutes): call get_label_quote, show the creator the price, and only with their yes pass the token here. The box quoted (any parcel overrides) is the box bought, and the purchase is refused if the rate being bought costs more than the quote. PREREQUISITES: the order is paid, the buyer''s address is complete, and the creator''s ship-from is set. If a label already exists this returns a duplicate error. Reaches an external carrier API.'
tags:
- Orders
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 255
description: Replays the stored response for a repeat of the same call within 24h. Strongly recommended on every mutating call — agents retry on ambiguous network failures, and without a key a retry creates a second listing, post, or message.
- name: X-Fanvault-Dry-Run
in: header
required: false
schema:
type: string
enum:
- '1'
description: Run every precondition and return the change that would be made, writing nothing.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
creator:
type: string
maxLength: 64
description: 'Which creator to act on: a creator UUID or @handle. Required for admin/agency tokens that manage multiple creators and for tokens restricted to more than one creator (see list_managed_creators); omit it when the token is pinned to exactly one creator or you are the creator.'
order_id:
type: string
format: uuid
description: Order UUID from list_orders.
confirmation_token:
type: string
minLength: 16
maxLength: 2000
description: confirmation_token from get_label_quote for this order. Expires 10 minutes after the quote.
required:
- order_id
- confirmation_token
additionalProperties: false
responses:
'200':
description: Tool result.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
type: object
properties:
type:
type: string
text:
type: string
required:
- type
- text
structuredContent:
type: object
properties:
creator:
type: object
properties:
id:
type: string
handle:
type:
- string
- 'null'
required:
- id
- handle
additionalProperties: true
additionalProperties: true
required:
- content
'400':
description: Invalid params, or the acting creator is ambiguous.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Token lacks the required scope, or targets a creator it may not act on.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown tool, or the referenced resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A precondition is unmet (payouts not connected, ship-from unset, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: The action was understood but could not be completed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limited. Honor Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/tools/get_order:
post:
operationId: get_order
summary: Get order
description: 'Fetches one order in full: line item, money breakdown (cents), payout status, label/tracking state, and the buyer''s ship-to city/state/ZIP (street address is withheld — shipping labels are generated server-side via generate_shipping_label).'
tags:
- Orders
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 255
description: Replays the stored response for a repeat of the same call within 24h. Strongly recommended on every mutating call — agents retry on ambiguous network failures, and without a key a retry creates a second listing, post, or message.
- name: X-Fanvault-Dry-Run
in: header
required: false
schema:
type: string
enum:
- '1'
description: Run every precondition and return the change that would be made, writing nothing.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
creator:
type: string
maxLength: 64
description: 'Which creator to act on: a creator UUID or @handle. Required for admin/agency tokens that manage multiple creators and for tokens restricted to more than one creator (see list_managed_creators); omit it when the token is pinned to exactly one creator or you are the creator.'
order_id:
type: string
format: uuid
description: Order UUID from list_orders.
required:
- order_id
additionalProperties: false
responses:
'200':
description: Tool result.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
type: object
properties:
type:
type: string
text:
type: string
required:
- type
- text
structuredContent:
type: object
properties:
creator:
type: object
properties:
id:
type: string
handle:
type:
- string
- 'null'
required:
- id
- handle
additionalProperties: true
additionalProperties: true
required:
- content
'400':
description: Invalid params, or the acting creator is ambiguous.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Token lacks the required scope, or targets a creator it may not act on.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown tool, or the referenced resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A precondition is unmet (payouts not connected, ship-from unset, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: The action was understood but could not be completed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limited. Honor Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/tools/list_orders:
post:
operationId: list_orders
summary: List orders
description: Lists the creator's sales orders newest first with money fields (cents), payout/transfer status, and tracking info. Defaults to OPEN orders (pending, paid, shipped) — pass status to see everything. Paginated via next_cursor. Orders with status "paid" and no tracking are awaiting shipment.
tags:
- Orders
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 255
description: Replays the stored response for a repeat of the same call within 24h. Strongly recommended on every mutating call — agents retry on ambiguous network failures, and without a key a retry creates a second listing, post, or message.
- name: X-Fanvault-Dry-Run
in: header
required: false
schema:
type: string
enum:
- '1'
description: Run every precondition and return the change that would be made, writing nothing.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
creator:
type: string
maxLength: 64
description: 'Which creator to act on: a creator UUID or @handle. Required for admin/agency tokens that manage multiple creators and for tokens restricted to more than one creator (see list_managed_creators); omit it when the token is pinned to exactly one creator or you are the creator.'
status:
type: string
enum:
- pending
- paid
- shipped
- delivered
- cancelled
- refunded
- all
description: 'Filter by order status. Default: open orders (pending/paid/shipped).'
limit:
type: integer
minimum: 1
maximum: 100
description: Page size (default 20).
cursor:
type: string
description: Opaque cursor from next_cursor.
additionalProperties: false
responses:
'200':
description: Tool result.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
type: object
properties:
type:
type: string
text:
type: string
required:
- type
- text
structuredContent:
type: object
properties:
creator:
type: object
properties:
id:
type: string
handle:
type:
- string
- 'null'
required:
- id
- handle
additionalProperties: true
additionalProperties: true
required:
- content
'400':
description: Invalid params, or the acting creator is ambiguous.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Token lacks the required scope, or targets a creator it may not act on.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown tool, or the referenced resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A precondition is unmet (payouts not connected, ship-from unset, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: The action was understood but could not be completed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limited. Honor Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/tools/mark_order_shipped:
post:
operationId: mark_order_shipped
summary: Mark order shipped
description: Marks a paid order as shipped and notifies the buyer. Optionally set a manual carrier + tracking_number first (use this when shipping without a Fanvault-generated label). Fails if the order isn't paid or is already shipped.
tags:
- Orders
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 255
description: Replays the stored response for a repeat of the same call within 24h. Strongly recommended on every mutating call — agents retry on ambiguous network failures, and without a key a retry creates a second listing, post, or message.
- name: X-Fanvault-Dry-Run
in: header
required: false
schema:
type: string
enum:
- '1'
description: Run every precondition and return the change that would be made, writing nothing.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
creator:
type: string
maxLength: 64
description: 'Which creator to act on: a creator UUID or @handle. Required for admin/agency tokens that manage multiple creators and for tokens restricted to more than one creator (see list_managed_creators); omit it when the token is pinned to exactly one creator or you are the creator.'
order_id:
type: string
format: uuid
carrier:
type: string
maxLength: 60
description: Carrier name for manual tracking (e.g. USPS).
tracking_number:
type: string
maxLength: 120
description: Manual tracking number.
required:
- order_id
additionalProperties: false
responses:
'200':
description: Tool result.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
type: object
properties:
type:
type: string
text:
type: string
required:
- type
- text
structuredContent:
type: object
properties:
creator:
type: object
properties:
id:
type: string
handle:
type:
- string
- 'null'
required:
- id
- handle
additionalProperties: true
additionalProperties: true
required:
- content
'400':
description: Invalid params, or the acting creator is ambiguous.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Token lacks the required scope, or targets a creator it may not act on.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown tool, or the referenced resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A precondition is unmet (payouts not connected, ship-from unset, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: The action was understood but could not be completed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limited. Honor Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
hint:
type: string
retryAfterSeconds:
type: integer
details: {}
required:
- code
- message
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'A Fanvault personal access token (fv_mcp_…), created at /settings/cli or /settings/mcp, or an OAuth 2.1 access token. Sent as `Authorization: Bearer <token>`.'
x-mcp:
endpoint: https://fanvault.shop/mcp
transport: streamable-http
spec_revision: '2025-11-25'
auth: Bearer PAT (fv_mcp_…) or OAuth 2.1
scopes:
- read
- write
- destructive
- payments
tool_count: 82
x-fanvault:
manifest: https://fanvault.shop/api/v1/manifest
manifest_version: 1
tools_hash: 385678b0326a5acd4c4ad0e412991ec0c9a510ea57eb743899b7c40ad0a5ecf4
min_cli_version: 0.1.0
cli:
install: npm i -g fanvault
docs: https://fanvault.shop/developers/cli