{ "openapi": "3.1.0", "info": { "title": "Pure Public API", "description": "Public API for accessing Pure marketplace data including products, spot prices, and more.", "version": "2.0.0", "license": { "name": "Proprietary" } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "API key for authentication" } }, "schemas": {} }, "paths": { "/": { "get": { "summary": "API Information", "tags": [ "Root" ], "description": "Get information about the API and available endpoints", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "documentation": { "type": "string" }, "endpoints": { "type": "object", "properties": { "swagger": { "type": "string" }, "health": { "type": "string" } }, "required": [ "swagger", "health" ], "additionalProperties": false } }, "required": [ "name", "version", "description", "endpoints" ], "additionalProperties": false } } } } } } }, "/products/get-product-analytics/v1": { "get": { "summary": "Get product analytics", "tags": [ "Products" ], "description": "Retrieve all product analytics\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "productId", "required": true, "description": "The ID of the product to get analytics for" }, { "schema": { "type": "string" }, "in": "query", "name": "variantId", "required": true, "description": "The ID of the variant to get analytics for" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "range", "required": true, "description": "The range of days to get analytics for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "marketPrice": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false }, "premium": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false }, "depth": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false } }, "required": [ "marketPrice", "premium", "depth" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-activity/v1": { "get": { "summary": "Get product activity", "tags": [ "Products" ], "description": "Retrieve all product activity\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "productId", "required": true, "description": "The ID of the product to get activity for" }, { "schema": { "type": "string" }, "in": "query", "name": "variantId", "required": true, "description": "The ID of the variant to get activity for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "createdAt": { "type": "string" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "event", "createdAt", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-order-book/v1": { "get": { "summary": "Get product order book", "tags": [ "Products (Legacy)" ], "description": "Retrieve the order book for a product\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "variantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "isUsersOrder": { "type": "boolean" }, "usersQty": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar", "isUsersOrder", "usersQty" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "isUsersOrder": { "type": "boolean" }, "usersQty": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar", "isUsersOrder", "usersQty" ], "additionalProperties": false } } }, "required": [ "listings", "offers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/orderbook/v2": { "get": { "summary": "Get live orderbook for a product", "tags": [ "Products" ], "description": "Retrieve the live orderbook for a product across all variants. Returns active listings and offers from the `orderbook_listing_live` and `orderbook_offer_live` views (already filtered to active, non-expired, trading-enabled organizations).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantTitle": { "type": "string" }, "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumPercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "premiumPercent", "premiumDollar", "type", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumPercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "premiumPercent", "premiumDollar", "type", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "variantId", "variantTitle", "listings", "offers" ], "additionalProperties": false } } }, "required": [ "productId", "variants" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/v3": { "get": { "summary": "Get enriched product details", "tags": [ "Products" ], "description": "Retrieve a single product with all variants (including best offer/listing and order book per variant) and recent activity.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "orderBook": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "listings", "offers" ], "additionalProperties": false } }, "required": [ "id", "title", "highestOffer", "lowestListing", "images", "orderBook" ], "additionalProperties": false } }, "recentActivity": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "createdAt": { "type": "string" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "event", "createdAt", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants", "recentActivity" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/catalog/v1": { "get": { "summary": "Get product catalog metadata", "tags": [ "Products" ], "description": "Retrieve all product catalog metadata in a single request \u2014 categories, subcategories, manufacturers, materials, attributes, and certificate providers.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "isNumismatic": { "type": "boolean" }, "allowCardPayments": { "type": "boolean" }, "isInstantShip": { "type": "boolean" }, "requireImmediateCapture": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "description", "createdAt", "isNumismatic", "allowCardPayments", "isInstantShip", "requireImmediateCapture", "updatedAt" ], "additionalProperties": false } }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumCalculationType": { "type": "string", "enum": [ "unit", "troy_ounce" ] }, "feeRate": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "advancedFeeRate": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "title", "description", "premiumCalculationType", "feeRate", "advancedFeeRate" ], "additionalProperties": false } }, "manufacturers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isEsg": { "type": "boolean" } }, "required": [ "id", "title", "description", "updatedAt", "createdAt", "images", "isEsg" ], "additionalProperties": false } }, "materials": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "title", "description" ], "additionalProperties": false } }, "certificateProviders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "createdAt", "description", "title" ], "additionalProperties": false } } }, "required": [ "categories", "subcategories", "manufacturers", "materials", "attributes", "certificateProviders" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/search/v1": { "get": { "summary": "Search products", "tags": [ "Products" ], "description": "Search and browse products with full-text search, filtering, and facets. Returns enriched product data with variants hydrated from the database.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query. Omit or pass '*' to browse all products." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 250 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 250)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "subCategory": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "purity": { "type": "string" }, "premiumCalculationType": { "type": "string" }, "certificateProvider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "images": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sortKey": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "listing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" } }, "required": [ "id", "price", "spotPremium", "spotPremiumDollar", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "offer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" } }, "required": [ "id", "price", "spotPremium", "spotPremiumDollar", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "flags": { "type": "object", "properties": { "isStockedByBbStore": { "type": "boolean" }, "isCertified": { "type": "boolean" }, "isEsg": { "type": "boolean" }, "isIra": { "type": "boolean" }, "isNumismatic": { "type": "boolean" }, "hasListing": { "type": "boolean" }, "hasOffer": { "type": "boolean" } }, "additionalProperties": false }, "viewCount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "subCategory", "material", "manufacturer", "weight", "weightGrams", "purity", "premiumCalculationType", "viewCount" ], "additionalProperties": false } }, "total": { "type": "number" }, "facets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "totalValues": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field", "counts" ], "additionalProperties": false } } }, "required": [ "products", "total" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/search-products/v2": { "get": { "summary": "Search products", "tags": [ "Products (Legacy)" ], "description": "Search for products. When no query is provided, returns all products with pagination.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": true, "description": "Search query string" }, { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "in": "query", "name": "pagination", "required": false, "description": "Pagination parameters (limit and offset)" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "found": { "type": "number" }, "hits": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "sub_category": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weight_grams": { "type": "number" }, "purity": { "type": "string" }, "premium_calculation_type": { "type": "string" }, "certificate_provider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "variants": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "listing_id": { "type": "string" }, "listing_price": { "type": "number" }, "listing_spot_premium": { "type": "number" }, "listing_spot_premium_dollar": { "type": "number" }, "listing_expires_at": { "type": "string" }, "offer_id": { "type": "string" }, "offer_price": { "type": "number" }, "offer_spot_premium": { "type": "number" }, "offer_spot_premium_dollar": { "type": "number" }, "offer_expires_at": { "type": "string" }, "is_stocked_by_bb_store": { "type": "boolean" }, "is_certified": { "type": "boolean" }, "is_esg": { "type": "boolean" }, "is_ira": { "type": "boolean" }, "is_numismatic": { "type": "boolean" }, "has_listing": { "type": "boolean" }, "has_offer": { "type": "boolean" }, "favorite_count": { "type": "number" }, "view_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "sub_category", "material", "manufacturer", "weight", "weight_grams", "purity", "premium_calculation_type", "view_count" ], "additionalProperties": false }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "snippet": { "type": "string" }, "matched_tokens": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } ] } }, "required": [ "field", "matched_tokens" ], "additionalProperties": false } }, "text_match": { "type": "number" }, "text_match_info": { "type": "object", "properties": { "best_field_score": { "type": "string" }, "best_field_weight": { "type": "number" }, "fields_matched": { "type": "number" }, "score": { "type": "string" }, "tokens_matched": { "type": "number" } }, "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } }, "facet_counts": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "highlighted": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "total_values": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field_name", "counts" ], "additionalProperties": false } }, "page": { "type": "number" }, "out_of": { "type": "number" }, "search_time_ms": { "type": "number" }, "request_params": { "type": "object", "properties": { "collection_name": { "type": "string" }, "per_page": { "type": "number" }, "q": { "type": "string" } }, "additionalProperties": false } }, "required": [ "found" ], "additionalProperties": false } } } } } } }, "/products/search-products/v3": { "get": { "summary": "Search products", "tags": [ "Products (Legacy)" ], "description": "Search for products. When no query is provided, returns all products with pagination.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query. Omit or pass '*' to browse all products." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 250 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 250)" }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "sub_category": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weight_grams": { "type": "number" }, "purity": { "type": "string" }, "premium_calculation_type": { "type": "string" }, "certificate_provider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sortKey": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "images": { "type": "array", "items": { "type": "string" } }, "listing_id": { "type": "string" }, "listing_price": { "type": "number" }, "listing_spot_premium": { "type": "number" }, "listing_spot_premium_dollar": { "type": "number" }, "listing_expires_at": { "type": "string" }, "offer_id": { "type": "string" }, "offer_price": { "type": "number" }, "offer_spot_premium": { "type": "number" }, "offer_spot_premium_dollar": { "type": "number" }, "offer_expires_at": { "type": "string" }, "is_stocked_by_bb_store": { "type": "boolean" }, "is_certified": { "type": "boolean" }, "is_esg": { "type": "boolean" }, "is_ira": { "type": "boolean" }, "is_numismatic": { "type": "boolean" }, "has_listing": { "type": "boolean" }, "has_offer": { "type": "boolean" }, "favorite_count": { "type": "number" }, "view_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "sub_category", "material", "manufacturer", "weight", "weight_grams", "purity", "premium_calculation_type", "view_count" ], "additionalProperties": false } }, "total": { "type": "number" }, "facets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "total_values": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field", "counts" ], "additionalProperties": false } } }, "required": [ "products", "total" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-options/v1": { "get": { "summary": "Get product options", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product options with images, categories, and variants\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "value", "label", "variants" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-certificate-providers/v1": { "get": { "summary": "Get certificate providers", "tags": [ "Products" ], "description": "Retrieve all product certificate providers\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "createdAt", "description", "title" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-attributes/v1": { "get": { "summary": "Get product attributes", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product attributes\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "title", "description" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-materials/v1": { "get": { "summary": "Get product materials", "tags": [ "Products" ], "description": "Retrieve all product materials\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "enum": [ "Gold", "Silver", "Platinum", "Palladium", "Bitcoin" ] } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-products/v1": { "get": { "summary": "Get products by IDs", "tags": [ "Products (Legacy)" ], "description": "Retrieve products by their IDs with variants, offers, and listings\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ids", "required": true, "description": "Comma separated list of product IDs to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "title", "highestOffer", "lowestListing", "images" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-products/v2": { "get": { "summary": "Get products with filtering", "tags": [ "Products (Legacy)" ], "description": "Retrieve products filtered by material and attributes, with variants, offers, and listings. Returns paginated results.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "material", "required": false, "description": "Filter by material (Gold, Silver, Platinum, Palladium, Bitcoin)" }, { "schema": { "type": "string" }, "in": "query", "name": "attributeIds", "required": false, "description": "Comma separated attribute IDs (AND semantics)" }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "title", "highestOffer", "lowestListing", "images" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants" ], "additionalProperties": false } }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false } } } } } } }, "/products/get-product-categories/v1": { "get": { "summary": "Get product categories", "tags": [ "Products" ], "description": "Retrieve all product categories\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "isNumismatic": { "type": "boolean" }, "allowCardPayments": { "type": "boolean" }, "isInstantShip": { "type": "boolean" }, "requireImmediateCapture": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "description", "createdAt", "isNumismatic", "allowCardPayments", "isInstantShip", "requireImmediateCapture", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-subcategories/v1": { "get": { "summary": "Get product subcategories", "tags": [ "Products" ], "description": "Retrieve all product subcategories\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumCalculationType": { "type": "string", "enum": [ "unit", "troy_ounce" ] }, "feeRate": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "advancedFeeRate": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "title", "description", "premiumCalculationType", "feeRate", "advancedFeeRate" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-manufacturers/v1": { "get": { "summary": "Get product manufacturers", "tags": [ "Products" ], "description": "Retrieve all product manufacturers\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isEsg": { "type": "boolean" } }, "required": [ "id", "title", "description", "updatedAt", "createdAt", "images", "isEsg" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-spot-price/v1": { "get": { "summary": "Get spot price", "tags": [ "Marketplace" ], "description": "Retrieve current spot prices for all precious metals. This endpoint returns the current bid/ask prices, market status, and price changes for all supported materials.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "material": { "type": "string", "enum": [ "Gold", "Silver", "Platinum", "Palladium", "Bitcoin" ] }, "bid": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ask": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "changePositive": { "type": "boolean" }, "changePrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "material", "bid", "ask", "changePositive", "changePrice" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-recommended-shipping-date/v1": { "get": { "summary": "Get recommended shipping date", "tags": [ "Marketplace" ], "description": "Retrieve the recommended shipping date for the product. This endpoint returns the two day and overnight shipping dates.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "twoDayLabel": { "type": "string", "format": "date-time" }, "overnightLabel": { "type": "string", "format": "date-time" } }, "required": [ "twoDayLabel", "overnightLabel" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-sitemap-products/v1": { "get": { "summary": "Get sitemap products", "tags": [ "Marketplace" ], "description": "Retrieve all products for the sitemap. This endpoint returns the sku and updatedAt for all products.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "sku", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-marketplace-stats/v1": { "get": { "summary": "Get platform-wide marketplace statistics", "tags": [ "Marketplace" ], "description": "Retrieve aggregate marketplace statistics including total ask/bid amounts, listing/offer counts, and product counts. Stats are recalculated every minute.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalAskAmount": { "type": "number", "description": "Total value of all active listings in cents" }, "totalBidAmount": { "type": "number", "description": "Total value of all active offers in cents" }, "totalListingCount": { "type": "number", "description": "Total number of active listings" }, "totalOfferCount": { "type": "number", "description": "Total number of active offers" }, "totalProductCount": { "type": "number", "description": "Total number of products with active orderbook entries" }, "updatedAt": { "type": "string", "description": "When the stats were last calculated" } }, "required": [ "totalAskAmount", "totalBidAmount", "totalListingCount", "totalOfferCount", "totalProductCount", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/organization/get-organization/v1": { "get": { "summary": "Get organization details", "tags": [ "Organization" ], "description": "Get the organization details associated with the authenticated API key. Sensitive fields such as access tokens and internal IDs are excluded.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tradingEnabled": { "type": "boolean" }, "vacationMode": { "type": "boolean" }, "payoutMethod": { "type": "string" }, "electronicCheckName": { "type": "string" }, "electronicCheckEmail": { "type": "string" }, "apiEnabled": { "type": "boolean" }, "onboardingStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "createdAt", "updatedAt", "tradingEnabled", "vacationMode", "payoutMethod", "electronicCheckName", "electronicCheckEmail", "apiEnabled", "onboardingStatus" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/organization/update-organization/v1": { "patch": { "summary": "Update organization settings", "tags": [ "Organization" ], "description": "Update one or more settings for the authenticated organization. Only the provided fields will be modified. Supports vacation mode, payout method, and electronic check details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vacationMode": { "description": "Enable or disable vacation mode. When active, listings and offers are hidden from the marketplace.", "type": "boolean" }, "payoutMethod": { "description": "Default payout method for the organization", "type": "string", "enum": [ "electronic_check", "teller_ach" ] }, "electronicCheckName": { "description": "Payee name for electronic check payouts", "type": "string", "maxLength": 40 }, "electronicCheckEmail": { "description": "Payee email for electronic check payouts", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "vacationMode": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "electronic_check", "teller_ach", "wire_transfer", "plaid_ach" ] }, "electronicCheckName": { "type": "string" }, "electronicCheckEmail": { "type": "string" } }, "required": [ "vacationMode", "payoutMethod", "electronicCheckName", "electronicCheckEmail" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/organization/get-watchlist/v1": { "get": { "summary": "List organization watchlist items", "tags": [ "Organization" ], "description": "Retrieve product watchlist items for members of the authenticated organization. Results include related product and variant details and can be filtered by product ID.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of watchlist items to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of watchlist items to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" }, "memberId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "createdAt", "memberId", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/organization/create-watchlist/v1": { "post": { "summary": "Add a product to the watchlist", "tags": [ "Organization" ], "description": "Add a product variant to the authenticated member's watchlist. The item is scoped to the API key's organization. Duplicate product and variant combinations for the same member are rejected.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Product to add to the watchlist" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Product variant to add to the watchlist" } }, "required": [ "productId", "variantId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" } }, "required": [ "id", "productId", "variantId", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/organization/update-watchlist/v1": { "patch": { "summary": "Update a watchlist item", "tags": [ "Organization" ], "description": "Update the product or variant on a watchlist item owned by a member of the authenticated organization. Only the provided fields are modified.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlistId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Watchlist item ID" }, "productId": { "description": "Replacement product ID", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "description": "Replacement product variant ID", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "watchlistId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" } }, "required": [ "id", "productId", "variantId", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/organization/delete-watchlist/v1": { "delete": { "summary": "Remove a watchlist item", "tags": [ "Organization" ], "description": "Permanently remove a watchlist item owned by a member of the authenticated organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlistId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Watchlist item ID" } }, "required": [ "watchlistId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } } } } }, "/orders/get-purchase-orders/v1": { "get": { "summary": "List purchase orders", "tags": [ "Orders" ], "description": "List orders where Pure is buying from you \u2014 the records created by a **sell** execute. `orderId` from `POST /execution/v2/sell/quotes/:quoteId/execute` is this id. Labels appear on `shippingLabelUrl` after fulfillment generates them (not at execute time). Scoped to the API key's organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "pending_confirmation", "ready_for_shipment", "in_transit", "items_received", "check_in_progress", "order_complete", "order_cancelled", "check_in_complete" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by order status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of orders to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of orders to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "trackingIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending_confirmation", "ready_for_shipment", "in_transit", "items_received", "check_in_progress", "order_complete", "order_cancelled", "check_in_complete" ] }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "shipping": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Shipping fee in cents" }, "processingFee": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Processing fee in cents" }, "total": { "type": "number", "description": "Order total in cents" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingLabelUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Outbound shipping-label URL once generated. Null until fulfillment creates the label \u2014 poll this endpoint; it is not instant after execute." }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "trackingIds", "status", "subtotal", "salesTax", "shipping", "processingFee", "total", "currency", "shippingLabelUrl", "createdAt", "updatedAt", "completeAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/orders/get-purchase-order/v1": { "get": { "summary": "Get a purchase order", "tags": [ "Orders" ], "description": "Retrieve a single purchase order by ID for the authenticated organization. `id` is the `orderId` returned by `POST /execution/v2/sell/quotes/:quoteId/execute`. Use `shippingLabelUrl` to poll for the outbound shipping label \u2014 it is null until fulfillment generates it.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "number", "exclusiveMinimum": 0 }, "in": "query", "name": "id", "required": true, "description": "Purchase order ID \u2014 the orderId from sell execute" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "trackingIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending_confirmation", "ready_for_shipment", "in_transit", "items_received", "check_in_progress", "order_complete", "order_cancelled", "check_in_complete" ] }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "shipping": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Shipping fee in cents" }, "processingFee": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Processing fee in cents" }, "total": { "type": "number", "description": "Order total in cents" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingLabelUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Outbound shipping-label URL once generated. Null until fulfillment creates the label \u2014 poll this endpoint; it is not instant after execute." }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "trackingIds", "status", "subtotal", "salesTax", "shipping", "processingFee", "total", "currency", "shippingLabelUrl", "createdAt", "updatedAt", "completeAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/orders/get-sale-orders/v1": { "get": { "summary": "List sale orders", "tags": [ "Orders" ], "description": "List orders where Pure is selling to you \u2014 the records created by a **buy** execute. `orderId` from `POST /execution/v2/buy/quotes/:quoteId/execute` is this id. Scoped to the API key's organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "awaiting_payment", "payment_processing", "fufillment_in_progress", "payment_failed", "order_shipped", "order_complete", "order_cancelled", "partially_fufilled" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by order status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of orders to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of orders to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_processing", "fufillment_in_progress", "payment_failed", "order_shipped", "order_complete", "order_cancelled", "partially_fufilled" ] }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "shipping": { "type": "number", "description": "Shipping fee in cents" }, "processingFee": { "type": "number", "description": "Processing fee in cents" }, "total": { "type": "number", "description": "Order total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "type": "number", "description": "Price in cents" }, "quantity": { "type": "number" }, "tracking": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingService": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "item_recieved", "check_in_progress", "item_complete", "item_returned", "item_adjusted", "item_pending" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "tracking", "shippingService", "status", "createdAt", "updatedAt" ], "additionalProperties": false } }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "subtotal", "salesTax", "shipping", "processingFee", "total", "currency", "lineItems", "createdAt", "updatedAt", "completeAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/listings/create-listing/v1": { "post": { "summary": "Create a listing", "tags": [ "Listings" ], "description": "Create a new orderbook listing for the authenticated organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "price": { "description": "Price in cents. Required for fixed_pricing type", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "inventoryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maxSpotPrice": { "description": "Max spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "description": "Min spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "productId", "variantId", "quantity", "type" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "maxSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiryNotifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instantPayout": { "type": "boolean" }, "beachInventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "expiresAt", "updatedAt", "createdAt", "sellerNotes", "premiumPercent", "type", "premiumDollar", "spotPremium", "quantity", "active", "spotPremiumDollar", "inventoryId", "maxSpotPrice", "minSpotPrice", "expiryNotifiedAt", "instantPayout", "beachInventoryId" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/listings/get-listings/v1": { "get": { "summary": "List your organization's orderbook listings", "tags": [ "Listings (Legacy)" ], "description": "Retrieve orderbook listings for the authenticated organization with optional filtering by active status and product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "active", "required": false, "description": "Filter by active status" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of listings to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of listings to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "expiryNotifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instantPayout": { "type": "boolean" }, "beachInventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "expiresAt", "updatedAt", "createdAt", "sellerNotes", "premiumPercent", "type", "premiumDollar", "spotPremium", "quantity", "active", "spotPremiumDollar", "inventoryId", "expiryNotifiedAt", "instantPayout", "beachInventoryId", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/listings/get-listings/v2": { "get": { "summary": "List your organization's live listings", "tags": [ "Listings" ], "description": "Retrieve live orderbook listings for the authenticated organization. Only returns active, non-expired listings with valid pricing from trading-enabled organizations (via `orderbook_listing_live` view).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of listings to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of listings to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "premiumPercent": { "type": "number" }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "quantity", "premiumPercent", "premiumDollar", "type", "spotPremium", "spotPremiumDollar", "sellerNotes", "inventoryId", "active", "expiresAt", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/listings/get-listing-stats/v1": { "get": { "summary": "Get listing statistics for your organization", "tags": [ "Listings" ], "description": "Retrieve aggregate statistics about the authenticated organization's orderbook listings, including counts, quantities, and total value.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalListings": { "type": "number" }, "activeListings": { "type": "number" }, "inactiveListings": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalValue": { "type": "number", "description": "Sum of price * quantity in cents" } }, "required": [ "totalListings", "activeListings", "inactiveListings", "totalQuantity", "totalValue" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/listings/delete-listing/v1": { "delete": { "summary": "Deactivate a listing", "tags": [ "Listings" ], "description": "Deactivate an orderbook listing owned by the authenticated organization. This sets the listing's active status to false rather than permanently deleting it.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "listingId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } } } } }, "/listings/update-listing/v1": { "patch": { "summary": "Update a listing", "tags": [ "Listings" ], "description": "Update fields on an orderbook listing owned by the authenticated organization. Only the provided fields will be updated.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "description": "Price in cents", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "quantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "listingId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "active", "sellerNotes", "updatedAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/offers/create-offer/v1": { "post": { "summary": "Create an offer", "tags": [ "Offers" ], "description": "Create a new orderbook offer (bid) for the authenticated organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "price": { "description": "Price in cents. Required for fixed_pricing type", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "maxSpotPrice": { "description": "Max spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "description": "Min spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "productId", "variantId", "quantity", "type", "expiresAt" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiryNotifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentDestination": { "type": "string", "enum": [ "address_on_file", "pure_vault" ] } }, "required": [ "id", "productId", "variantId", "price", "updatedAt", "expiresAt", "quantity", "buyerNotes", "createdAt", "premiumPercent", "type", "premiumDollar", "spotPremium", "active", "spotPremiumDollar", "maxSpotPrice", "minSpotPrice", "expiryNotifiedAt", "fulfillmentDestination" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/offers/get-offers/v1": { "get": { "summary": "List your organization's orderbook offers", "tags": [ "Offers (Legacy)" ], "description": "Retrieve orderbook offers (bids) for the authenticated organization with optional filtering by active status and product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "active", "required": false, "description": "Filter by active status" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of offers to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of offers to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expiryNotifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentDestination": { "type": "string", "enum": [ "address_on_file", "pure_vault" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "updatedAt", "expiresAt", "quantity", "buyerNotes", "createdAt", "premiumPercent", "type", "premiumDollar", "spotPremium", "active", "spotPremiumDollar", "expiryNotifiedAt", "fulfillmentDestination", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/offers/get-offers/v2": { "get": { "summary": "List your organization's live offers", "tags": [ "Offers" ], "description": "Retrieve live orderbook offers for the authenticated organization. Only returns active, non-expired offers with valid pricing from trading-enabled organizations (via `orderbook_offer_live` view).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of offers to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of offers to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "premiumPercent": { "type": "number" }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "quantity", "premiumPercent", "premiumDollar", "type", "spotPremium", "spotPremiumDollar", "active", "expiresAt", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/offers/get-offer-stats/v1": { "get": { "summary": "Get offer statistics for your organization", "tags": [ "Offers" ], "description": "Retrieve aggregate statistics about the authenticated organization's orderbook offers (bids), including counts, quantities, and total value.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalOffers": { "type": "number" }, "activeOffers": { "type": "number" }, "inactiveOffers": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalValue": { "type": "number", "description": "Sum of price * quantity in cents" } }, "required": [ "totalOffers", "activeOffers", "inactiveOffers", "totalQuantity", "totalValue" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/offers/delete-offer/v1": { "delete": { "summary": "Deactivate an offer", "tags": [ "Offers" ], "description": "Deactivate an orderbook offer owned by the authenticated organization. This sets the offer's active status to false rather than permanently deleting it.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "offerId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } } } } }, "/offers/update-offer/v1": { "patch": { "summary": "Update an offer", "tags": [ "Offers" ], "description": "Update fields on an orderbook offer owned by the authenticated organization. Only the provided fields will be updated.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "description": "Price in cents", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "quantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "offerId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "active", "buyerNotes", "updatedAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/inventory/get-inventory/v1": { "get": { "summary": "List your organization's inventory", "tags": [ "Inventory" ], "description": "Retrieve inventory items for the authenticated organization with optional filtering by product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "purchasePricePer": { "type": "number", "description": "Purchase price per unit in cents" }, "purchaseSpotPrice": { "type": "number", "description": "Spot price at time of purchase in cents" }, "purchaseDate": { "type": "string" }, "purchaseSource": { "type": "string" }, "notes": { "type": "string" }, "certificateId": { "type": "string" }, "storedAt": { "type": "string" }, "createdAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "quantity", "purchasePricePer", "purchaseSpotPrice", "purchaseDate", "purchaseSource", "notes", "certificateId", "storedAt", "createdAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/inventory/get-inventory-stats/v1": { "get": { "summary": "Get inventory statistics for your organization", "tags": [ "Inventory" ], "description": "Retrieve aggregate statistics about the authenticated organization's inventory, including total items, quantities, cost basis, and unique product count.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalItems": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalCostBasis": { "type": "number", "description": "Sum of purchase_price_per * quantity across all inventory in cents" }, "uniqueProducts": { "type": "number" } }, "required": [ "totalItems", "totalQuantity", "totalCostBasis", "uniqueProducts" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-intake-shipments/v1": { "get": { "summary": "List vault intake shipments", "tags": [ "Vault" ], "description": "List inbound vault shipments for the authenticated organization, including line items with product details. Results are scoped to the API key's organization.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "created", "in_transit", "delivered", "under_inspection", "accepted", "partial_accept", "rejected" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by intake shipment status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "created", "in_transit", "delivered", "under_inspection", "accepted", "partial_accept", "rejected" ] }, "carrier": { "type": "string", "enum": [ "DHLExpress", "FedEx", "FedExDefault", "FedexSmartPost", "LoomisExpress", "OnTrac", "OntracV3", "UPS", "USPS" ] }, "trackingNumber": { "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedArrivalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } } }, "required": [ "id", "status", "carrier", "trackingNumber", "origin", "expectedArrivalAt", "receivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/vault/get-intake-shipment/v1": { "get": { "summary": "Get a vault intake shipment", "tags": [ "Vault" ], "description": "Retrieve a single inbound vault shipment by ID, including line items with product details. The shipment must belong to the authenticated organization.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "id", "required": true, "description": "Vault intake shipment ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "created", "in_transit", "delivered", "under_inspection", "accepted", "partial_accept", "rejected" ] }, "carrier": { "type": "string", "enum": [ "DHLExpress", "FedEx", "FedExDefault", "FedexSmartPost", "LoomisExpress", "OnTrac", "OntracV3", "UPS", "USPS" ] }, "trackingNumber": { "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedArrivalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } } }, "required": [ "id", "status", "carrier", "trackingNumber", "origin", "expectedArrivalAt", "receivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-fulfillment-requests/v1": { "get": { "summary": "List vault fulfillment requests", "tags": [ "Vault" ], "description": "List vault fulfillment requests for the authenticated organization, including line items and associated vault inventory details.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by fulfillment request status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string", "enum": [ "auto", "order" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultLineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "vaultLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "required": [ "id", "vaultLineItemId", "quantity", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "type", "status", "notes", "reviewedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/vault/get-fulfillment-request/v1": { "get": { "summary": "Get a vault fulfillment request", "tags": [ "Vault" ], "description": "Retrieve a single vault fulfillment request by ID, including line items and associated vault inventory details. The request must belong to the authenticated organization.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "id", "required": true, "description": "Vault fulfillment request ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string", "enum": [ "auto", "order" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultLineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "vaultLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "required": [ "id", "vaultLineItemId", "quantity", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "type", "status", "notes", "reviewedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-requests/v1": { "get": { "summary": "List vault outbound requests", "tags": [ "Vault" ], "description": "List vault outbound (withdrawal) requests for the authenticated organization, including line items and associated vault inventory details.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by outbound request status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingCarrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultLineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "outboundImages": { "type": "array", "items": { "type": "string" } }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedQuantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "vaultLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "required": [ "id", "vaultLineItemId", "quantity", "outboundImages", "verifiedAt", "verifiedQuantity", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "status", "notes", "reviewedAt", "shippedAt", "trackingCarrier", "trackingNumber", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-requests/v2": { "get": { "summary": "List vault outbound requests", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nList outbound vault requests for the authenticated organization's FBO account. Pass `includeLineItems=true` to include `items` on each request.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Page number (default 1)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "status", "required": false, "description": "Filter by vault status" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeLineItems", "required": true, "description": "When true, include nested line items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "totalItems": { "type": "number" }, "approvedBySystem": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "outboundRequestId": { "type": "string" }, "productId": { "type": "string" }, "inventoryItemId": { "type": "string" } }, "required": [ "id", "createdAt", "outboundRequestId", "productId", "inventoryItemId" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "totalItems", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "page", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-request/v1": { "get": { "summary": "Get a vault outbound request", "tags": [ "Vault" ], "description": "Retrieve a single vault outbound (withdrawal) request by ID, including line items and associated vault inventory details. The request must belong to the authenticated organization.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "id", "required": true, "description": "Vault outbound request ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "completed", "cancelled" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingCarrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultLineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "outboundImages": { "type": "array", "items": { "type": "string" } }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedQuantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "vaultLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "required": [ "id", "vaultLineItemId", "quantity", "outboundImages", "verifiedAt", "verifiedQuantity", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "status", "notes", "reviewedAt", "shippedAt", "trackingCarrier", "trackingNumber", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-request/v2": { "get": { "summary": "Get a vault outbound request", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nRetrieve a single outbound vault request. The request must belong to the authenticated organization's FBO account. `items` are always included.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "id", "required": true, "description": "Vault outbound request ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "totalItems": { "type": "number" }, "approvedBySystem": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "outboundRequestId": { "type": "string" }, "productId": { "type": "string" }, "inventoryItemId": { "type": "string" } }, "required": [ "id", "createdAt", "outboundRequestId", "productId", "inventoryItemId" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "totalItems", "createdAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-line-items/v1": { "get": { "summary": "List vault line items", "tags": [ "Vault" ], "description": "List vaulted inventory line items for the authenticated organization across all intake shipments. Useful for viewing current vault holdings and inspection status.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "vaultIntakeShipmentId", "required": false, "description": "Filter by vault intake shipment ID" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, "in": "query", "name": "fulfillmentStatus", "required": false, "description": "Filter by fulfillment status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of records to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "vaultIntakeShipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inspectionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "passed", "failed", "partial" ] }, { "type": "null" } ] }, "inspectionNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string", "enum": [ "hold_in_vault", "return_to_sender", "destroy", "manual_review" ] }, { "type": "null" } ] }, "dispositionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillmentStatus": { "anyOf": [ { "type": "string", "enum": [ "available", "locked", "fulfilled" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "vaultIntakeShipmentId", "productId", "variantId", "quantityDeclared", "quantityReceived", "quantityAccepted", "quantityRejected", "inspectionStatus", "inspectionNotes", "disposition", "dispositionReason", "fulfillmentStatus", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/vault/get-holdings/v1": { "get": { "summary": "Get vault holdings", "tags": [ "Vault" ], "description": "Aggregated vault inventory holdings for the authenticated organization, grouped by product and variant. Quantities mirror the dashboard vault holdings table: total accepted, pending for orders, used for orders, current in vault, and available. Each holding includes estimated sell value from current orderbook bids (same logic as the dashboard Value column).\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "holdings": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "productTitle": { "type": "string" }, "productImage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSku": { "type": "string" }, "variantTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalAccepted": { "type": "number" }, "fulfilled": { "type": "number" }, "pending": { "type": "number", "description": "Quantity reserved by pending fulfillment or outbound requests" }, "used": { "type": "number", "description": "Quantity reserved by approved fulfillment or outbound requests" }, "currentInVault": { "type": "number", "description": "Total accepted minus fulfilled" }, "available": { "type": "number", "description": "Quantity available for new orders or outbound requests" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated sell value in cents at current orderbook bids" }, "filledQuantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Quantity fillable at current orderbook bids" } }, "required": [ "productId", "variantId", "productTitle", "productImage", "productSku", "variantTitle", "totalAccepted", "fulfilled", "pending", "used", "currentInVault", "available", "value", "filledQuantity" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "totalShipped": { "type": "number" }, "currentInVault": { "type": "number" }, "pendingForOrders": { "type": "number" }, "usedForOrders": { "type": "number" }, "available": { "type": "number" }, "totalEstimatedValue": { "type": "number", "description": "Sum of estimated sell values across holdings with bids, in cents" }, "totalFillableQuantity": { "type": "number", "description": "Sum of fillable quantities across holdings with bids" } }, "required": [ "totalShipped", "currentInVault", "pendingForOrders", "usedForOrders", "available", "totalEstimatedValue", "totalFillableQuantity" ], "additionalProperties": false } }, "required": [ "holdings", "summary" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-intake-address/v1": { "get": { "summary": "Get vault intake address", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nRetrieve the default intake address for the authenticated organization's vault FBO account.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "street": { "type": "string" }, "addressLine2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "formatted": { "type": "string" }, "vaultId": { "type": "string" }, "placement": { "type": "string" } }, "required": [ "firstName", "lastName", "street", "addressLine2", "city", "state", "zip", "country", "formatted", "vaultId", "placement" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-inventory/v1": { "get": { "summary": "List vault inventory", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nList vault inventory for the authenticated organization. Mapped products include Pure catalog details; unmapped products return `product: null`. Filter with `inboundShipmentId` to list units created from an inbound shipment.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Page number (default 1)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "status", "required": false, "description": "Filter by vault status" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "inboundShipmentId", "required": false, "description": "Filter inventory created from this inbound shipment" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "internalIdentifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inboundShipmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serialNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "variantTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "sku", "material", "images", "variantId", "variantTitle" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "createdAt", "product" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "page", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } } } } }, "/vault/get-inventory-item/v1": { "get": { "summary": "Get a vault inventory item", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nRetrieve a vault inventory item for the authenticated organization. Mapped products include Pure catalog details; unmapped products return `product: null`.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "id", "required": true, "description": "Vault inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "internalIdentifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inboundShipmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serialNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "variantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "variantTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "sku", "material", "images", "variantId", "variantTitle" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "createdAt", "product" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-inbound-shipments/v1": { "get": { "summary": "List vault inbound shipments", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nList inbound vault shipments for the authenticated organization's FBO account. Pass `includeLineItems=true` to include `lineItems` (with `inventoryItemIds` after accept).\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Page number (default 1)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "status", "required": false, "description": "Filter by vault status" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeLineItems", "required": true, "description": "When true, include nested line items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "shipmentNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "productId": { "type": "string" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "checkedInAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "inventoryItemIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "createdAt", "productId", "quantityDeclared" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "page", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } } } } }, "/vault/get-inbound-shipment/v1": { "get": { "summary": "Get a vault inbound shipment", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nRetrieve a single inbound vault shipment. The shipment must belong to the authenticated organization's FBO account. Pass `includeLineItems=true` to include `lineItems` (with `inventoryItemIds` after accept).\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "id", "required": true, "description": "Vault inbound shipment ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeLineItems", "required": true, "description": "When true, include nested line items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "shipmentNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "productId": { "type": "string" }, "quantityDeclared": { "type": "number" }, "quantityReceived": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityAccepted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantityRejected": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "checkedInAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "inventoryItemIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "createdAt", "productId", "quantityDeclared" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-shipments/v1": { "get": { "summary": "List vault outbound shipments", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nList outbound vault shipments for the authenticated organization's FBO account. Pass `includeLineItems=true` to include `items` on each shipment.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Page number (default 1)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of records to return (default 20, max 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "status", "required": false, "description": "Filter by vault status" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeLineItems", "required": true, "description": "When true, include nested line items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "shippedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "outboundShipmentId": { "type": "string" }, "inventoryItemId": { "type": "string" }, "outboundRequestItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string" }, "inboundShipmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inboundShipmentLineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "outboundShipmentId", "inventoryItemId", "productId" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "page", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } } } } }, "/vault/get-outbound-shipment/v1": { "get": { "summary": "Get a vault outbound shipment", "tags": [ "Vault (Alpha)" ], "description": "**Alpha.** Subject to change.\n\nRetrieve a single outbound vault shipment. The shipment must belong to the authenticated organization's FBO account. Pass `includeLineItems=true` to include `items`.\n\n**Requires:** vault enabled on the organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "id", "required": true, "description": "Vault outbound shipment ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeLineItems", "required": true, "description": "When true, include nested line items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "fboAccountId": { "type": "string" }, "status": { "type": "string" }, "shippedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "outboundShipmentId": { "type": "string" }, "inventoryItemId": { "type": "string" }, "outboundRequestItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string" }, "inboundShipmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inboundShipmentLineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "outboundShipmentId", "inventoryItemId", "productId" ], "additionalProperties": false } } }, "required": [ "id", "fboAccountId", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/execution/buy/quote/v1": { "post": { "summary": "Create a buy quote", "tags": [ "Execution - Buy" ], "description": "**Deprecated:** use the v2 endpoint POST /execution/v2/buy/quotes instead. Create a new buy quote with the specified items. Returns a quoteId and a pricing snapshot. The quote expires in 60 seconds.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The listing ID to quote" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to buy" } }, "required": [ "listingId", "quantity" ] }, "description": "Items to include in the quote" }, "paymentMethod": { "type": "string", "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...). Required so the quote includes accurate payment-method-specific fees." } }, "required": [ "items", "paymentMethod" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } }, "get": { "summary": "Get a buy quote", "tags": [ "Execution - Buy" ], "description": "**Deprecated:** use the v2 endpoint GET /execution/v2/buy/quotes/:quoteId instead. Retrieve the current state and pricing of an existing buy quote. Returns a fresh pricing snapshot.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "quoteId", "required": true, "description": "The quote ID to retrieve" }, { "schema": { "type": "string" }, "in": "query", "name": "paymentMethod", "required": false, "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...) to refresh payment-method-specific fees" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/buy/v1": { "post": { "summary": "Execute a buy order", "tags": [ "Execution - Buy" ], "description": "**Deprecated:** use the v2 endpoint POST /execution/v2/buy/quotes/:quoteId/execute instead. Execute a previously created buy quote. Validates the quote, charges payment, and creates orders. The quote must not be expired.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID from /execution/buy/quote/v1" }, "expectedTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The total from the quote response, in cents. The order is rejected if the current total exceeds this value." }, "paymentMethod": { "type": "string", "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...)" }, "shipping": { "type": "object", "properties": { "name": { "type": "string", "description": "Recipient name" }, "line1": { "type": "string", "description": "Street address" }, "line2": { "description": "Apartment, suite, etc.", "type": "string" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal / ZIP code" }, "country": { "type": "string", "description": "Country code" }, "phone": { "description": "Phone number", "type": "string" } }, "required": [ "name", "line1", "city", "state", "postalCode", "country" ] } }, "required": [ "quoteId", "expectedTotal", "paymentMethod", "shipping" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "orderId": { "type": "number", "description": "The main order ID" }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number", "description": "Unit price in cents" }, "total": { "type": "number", "description": "Line total in cents" }, "success": { "type": "boolean" } }, "required": [ "lineItemId", "productId", "variantId", "quantity", "price", "total", "success" ], "additionalProperties": false } }, "checkout": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "expiresAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" }, "allowCardPayments": { "type": "boolean" }, "allowAch": { "type": "boolean" } }, "required": [ "id", "currency", "expiresAt", "lineItems", "fees", "salesTax", "subtotal", "total", "availableCount", "unavailableCount", "allowCardPayments", "allowAch" ], "additionalProperties": false } }, "required": [ "status", "orderId", "items", "checkout" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/sell/quote/v1": { "post": { "summary": "Create a sell quote", "tags": [ "Execution - Sell" ], "description": "**Deprecated:** use the v2 endpoint POST /execution/v2/sell/quotes instead. Create a new sell quote with the specified items. Each item can reference an offer ID or a product+variant pair. Returns a quoteId, pricing breakdown, and available optionals (e.g. instant payout). The quote expires in 60 seconds.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The offer ID to sell into" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to sell" } }, "required": [ "offerId", "quantity" ] }, { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The product ID to sell" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The variant ID to sell" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to sell" } }, "required": [ "productId", "variantId", "quantity" ] } ] }, "description": "Items to include in the sell quote. Each item can specify an offerId or a productId+variantId pair." }, "selectedOptionalIds": { "description": "Optional IDs to select (e.g. instant payout). The quote will reflect fees for selected optionals.", "type": "array", "items": { "type": "string" } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } }, "get": { "summary": "Get a sell quote", "tags": [ "Execution - Sell" ], "description": "**Deprecated:** use the v2 endpoint GET /execution/v2/sell/quotes/:quoteId instead. Retrieve the current state and pricing of an existing sell quote. Returns a fresh pricing snapshot. Optionally pass selectedOptionalIds to toggle add-on services like instant payout.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "quoteId", "required": true, "description": "The quote ID to retrieve" }, { "schema": { "type": "string" }, "in": "query", "name": "selectedOptionalIds", "required": false, "description": "Comma-separated optional IDs to select (e.g. 'instant_payout'). Updates which optionals are active for this pricing snapshot." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/sell/v1": { "post": { "summary": "Execute a sell order", "tags": [ "Execution - Sell" ], "description": "**Deprecated:** use the v2 endpoint POST /execution/v2/sell/quotes/:quoteId/execute instead. Execute a previously created sell quote. Validates the quote, creates sell orders, and initiates payout. The quote must not be expired.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID from /execution/sell/quote/v1" }, "expectedTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The total from the quote response, in cents. The order is rejected if the current total is less than this value (protects against payout decreases)." }, "selectedOptionalIds": { "description": "Optional IDs to confirm (e.g. instant payout). Must match the selections from the quote.", "type": "array", "items": { "type": "string" } }, "adjustListings": { "description": "When true, decrements the seller's active listings for the same products during checkout", "type": "boolean" }, "confirmListingMismatch": { "description": "When true, skips the error when sell quantity is less than listed quantity", "type": "boolean" } }, "required": [ "quoteId", "expectedTotal" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "orderId": { "type": "number", "description": "The main order ID" }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number", "description": "Unit price in cents" }, "total": { "type": "number", "description": "Line total in cents" }, "success": { "type": "boolean" } }, "required": [ "lineItemId", "productId", "variantId", "quantity", "price", "total", "success" ], "additionalProperties": false } }, "checkout": { "type": "object", "properties": { "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "lineItems", "fees", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "status", "orderId", "items", "checkout" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/payment-methods/v1": { "get": { "summary": "List payment methods", "tags": [ "Execution - Buy" ], "description": "List all Stripe payment methods for the authenticated organization, including which one is the default.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "defaultPaymentMethodId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The organization's default payment method ID" }, "paymentMethods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stripe payment method ID -- pass this as paymentMethodId when executing a buy" }, "type": { "type": "string", "description": "Stripe type (e.g. us_bank_account, card)" }, "paymentMethod": { "type": "string", "enum": [ "stripe_ach", "stripe" ], "description": "The paymentMethod value to pass when executing a buy" }, "isDefault": { "type": "boolean", "description": "Whether this is the organization's default payment method" }, "card": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "number" }, "expYear": { "type": "number" } }, "required": [ "brand", "last4", "expMonth", "expYear" ], "additionalProperties": false }, { "type": "null" } ] }, "bankAccount": { "anyOf": [ { "type": "object", "properties": { "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last4": { "type": "string" }, "accountType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bankName", "last4", "accountType" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "type", "paymentMethod", "isDefault", "card", "bankAccount" ], "additionalProperties": false } } }, "required": [ "defaultPaymentMethodId", "paymentMethods" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/payout-methods/v1": { "get": { "summary": "Get payout methods", "tags": [ "Execution - Sell" ], "description": "Retrieve the authenticated organization's payout configuration and instant payout credit information. Use the instant payout credit info to determine eligibility before selecting the instant payout optional in a sell quote.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "payoutMethod": { "type": "string", "enum": [ "electronic_check", "teller_ach", "wire_transfer" ], "description": "The organization's configured payout method" }, "electronicCheckName": { "type": "string", "description": "Payee name for electronic check payouts" }, "electronicCheckEmail": { "type": "string", "description": "Payee email for electronic check payouts" }, "instantPayout": { "type": "object", "properties": { "creditLimit": { "type": "number", "description": "Total instant payout credit limit in cents" }, "outstandingBalance": { "type": "number", "description": "Currently outstanding advances in cents" }, "availableCredit": { "type": "number", "description": "Remaining available credit in cents" } }, "required": [ "creditLimit", "outstandingBalance", "availableCredit" ], "additionalProperties": false } }, "required": [ "payoutMethod", "electronicCheckName", "electronicCheckEmail", "instantPayout" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/buy/quotes": { "post": { "summary": "Create a buy quote", "tags": [ "Execution - Buy" ], "description": "Create a new buy quote with the specified items. Returns a quoteId and a pricing snapshot. Promotion codes are previewed via POST /execution/v2/buy/quotes/:quoteId/promotion-preview and applied at execute time. The quote expires in 60 seconds.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The listing ID to quote" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to buy" } }, "required": [ "listingId", "quantity" ] }, "description": "Items to include in the quote" }, "paymentMethod": { "type": "string", "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...). Required so the quote includes accurate payment-method-specific fees." }, "selectedOptionalIds": { "description": "Optional addon IDs to select (e.g. vault_shipping)", "type": "array", "items": { "type": "string" } } }, "required": [ "items", "paymentMethod" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/buy/quotes/{quoteId}": { "get": { "summary": "Get a buy quote", "tags": [ "Execution - Buy" ], "description": "Retrieve the current state and pricing of an existing buy quote. Returns a fresh pricing snapshot.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "paymentMethod", "required": false, "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...) to refresh payment-method-specific fees" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "selectedOptionalIds", "required": false, "description": "Optional addon IDs to select (repeatable query param)" }, { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/buy/quotes/{quoteId}/optionals": { "get": { "summary": "List buy quote optionals", "tags": [ "Execution - Buy" ], "description": "Returns the addon catalog for a buy quote, including eligibility and fees. A partial catalog is returned when individual addon resolvers fail.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to list available optionals for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false } }, "partial": { "type": "boolean", "description": "True when one or more addon resolvers failed and the catalog is degraded" }, "errors": { "description": "Per-addon resolver failures when partial is true", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "additionalProperties": false } } }, "required": [ "optionals", "partial" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/buy/quotes/{quoteId}/promotion-preview": { "post": { "summary": "Preview buy promotion", "tags": [ "Execution - Buy" ], "description": "Preview how a promotion code affects quote pricing without committing. Loads the current checkout session, then calls the port promotion preview.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promotionCode": { "type": "string", "description": "The promotion code to preview" }, "paymentMethod": { "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...)", "type": "string" }, "selectedOptionalIds": { "description": "Optional addon IDs currently selected", "type": "array", "items": { "type": "string" } } }, "required": [ "promotionCode" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to preview a promotion against" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "applied" ] }, "appliedCode": { "type": "string" }, "totalDiscount": { "type": "number", "description": "Total discount in cents" }, "appliedPromotions": { "type": "array", "items": { "type": "object", "properties": { "promotionId": { "type": "string" }, "promotionType": { "type": "string" }, "category": { "type": "string", "enum": [ "shipping", "order", "fee_reprice" ] }, "label": { "type": "string" }, "discountAmount": { "type": "number", "description": "Discount amount in cents" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "sourceType": { "type": "string", "enum": [ "promotion_code", "referral_grant" ] }, "sourceCode": { "type": "string" }, "sourceCodeId": { "type": "string" }, "sourceGrantId": { "type": "string" } }, "required": [ "promotionId", "promotionType", "category", "label", "discountAmount", "params", "sourceType" ], "additionalProperties": false } }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false } }, "required": [ "status", "appliedCode", "totalDiscount", "appliedPromotions", "quote" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "attemptedCode": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "quote": { "anyOf": [ { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute, modify, or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "fees", "optionals", "subtotal", "total", "currency", "lineItems", "salesTax", "availableCount", "unavailableCount" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "status", "attemptedCode", "error", "quote" ], "additionalProperties": false } ] } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/buy/quotes/{quoteId}/execute": { "post": { "summary": "Execute a buy quote", "tags": [ "Execution - Buy" ], "description": "Execute a previously created buy quote. Validates pricing, charges payment, and creates orders.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The total from the quote response, in cents. The order is rejected if the current total exceeds this value." }, "paymentMethod": { "type": "string", "description": "'wire_transfer' or a Stripe payment method ID (pm_... or ba_...)" }, "shipping": { "description": "Shipping address when not using vault fulfillment", "type": "object", "properties": { "name": { "type": "string", "description": "Recipient name" }, "line1": { "type": "string", "description": "Street address" }, "line2": { "description": "Apartment, suite, etc.", "type": "string" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal / ZIP code" }, "country": { "type": "string", "description": "Country code" }, "phone": { "description": "Phone number", "type": "string" } }, "required": [ "name", "line1", "city", "state", "postalCode", "country" ] }, "selectedOptionalIds": { "description": "Optional addon IDs to confirm", "type": "array", "items": { "type": "string" } }, "promotionCode": { "description": "Promotion code to apply at checkout", "type": "string" }, "sweep": { "description": "When true, sweep remaining balance after a partial fill", "type": "boolean" } }, "required": [ "expectedTotal", "paymentMethod" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to execute" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "orderId": { "type": "number", "description": "The main order ID" }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number", "description": "Unit price in cents" }, "total": { "type": "number", "description": "Line total in cents" }, "success": { "type": "boolean" } }, "required": [ "lineItemId", "productId", "variantId", "quantity", "price", "total", "success" ], "additionalProperties": false } }, "checkout": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "expiresAt": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total in cents" }, "availableCount": { "type": "number" }, "unavailableCount": { "type": "number" }, "allowCardPayments": { "type": "boolean" }, "allowAch": { "type": "boolean" } }, "required": [ "id", "currency", "expiresAt", "lineItems", "fees", "salesTax", "subtotal", "total", "availableCount", "unavailableCount", "allowCardPayments", "allowAch" ], "additionalProperties": false }, "counterpartyOrderIds": { "type": "array", "items": { "type": "number" }, "description": "Sell order IDs created as the counterparty side of this buy" } }, "required": [ "status", "orderId", "items", "checkout", "counterpartyOrderIds" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes": { "post": { "summary": "Create a sell quote", "tags": [ "Execution - Sell" ], "description": "Create a new sell quote with the specified items. Each item can reference an offer ID or a product+variant pair. Returns a quoteId, pricing breakdown, and available optionals. The quote expires in 60 seconds.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The offer ID to sell into" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to sell" } }, "required": [ "offerId", "quantity" ] }, { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The product ID to sell" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The variant ID to sell" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999, "description": "Quantity to sell" } }, "required": [ "productId", "variantId", "quantity" ] } ] }, "description": "Items to include in the sell quote. Each item can specify an offerId or a productId+variantId pair." }, "selectedOptionalIds": { "description": "Optional IDs to select (e.g. instant payout). The quote will reflect fees for selected optionals.", "type": "array", "items": { "type": "string" } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes/{quoteId}": { "get": { "summary": "Get a sell quote", "tags": [ "Execution - Sell" ], "description": "Retrieve the current state and pricing of an existing sell quote. Returns a fresh pricing snapshot.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "selectedOptionalIds", "required": false, "description": "Optional addon IDs to select (repeatable query param, e.g. ?selectedOptionalIds=instant_payout)" }, { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes/{quoteId}/optionals": { "get": { "summary": "List sell quote optionals", "tags": [ "Execution - Sell" ], "description": "Returns the addon catalog for a sell quote, including eligibility and fees. A partial catalog is returned when individual addon resolvers fail.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to list available optionals for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false } }, "partial": { "type": "boolean", "description": "True when one or more addon resolvers failed and the catalog is degraded" }, "errors": { "description": "Per-addon resolver failures when partial is true", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "additionalProperties": false } } }, "required": [ "optionals", "partial" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes/{quoteId}/listing-conflicts": { "get": { "summary": "Check sell listing conflicts", "tags": [ "Execution - Sell" ], "description": "Pre-check whether sell quantities conflict with the seller's active listings for the quote line items.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to check listing conflicts for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "sellQuantity": { "type": "number" }, "listedQuantity": { "type": "number" }, "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" } }, "required": [ "id", "quantity", "price", "type" ], "additionalProperties": false } } }, "required": [ "productId", "variantId", "sellQuantity", "listedQuantity", "listings" ], "additionalProperties": false } } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes/{quoteId}/promotion-preview": { "post": { "summary": "Preview sell promotion", "tags": [ "Execution - Sell" ], "description": "Preview how a promotion code affects sell quote pricing without committing. Loads the current checkout session, then calls the port promotion preview.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promotionCode": { "type": "string", "description": "The promotion code to preview" }, "selectedOptionalIds": { "description": "Optional addon IDs currently selected", "type": "array", "items": { "type": "string" } } }, "required": [ "promotionCode" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to preview a promotion against" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "applied" ] }, "appliedCode": { "type": "string" }, "totalDiscount": { "type": "number", "description": "Total discount in cents" }, "appliedPromotions": { "type": "array", "items": { "type": "object", "properties": { "promotionId": { "type": "string" }, "promotionType": { "type": "string" }, "category": { "type": "string", "enum": [ "shipping", "order", "fee_reprice" ] }, "label": { "type": "string" }, "discountAmount": { "type": "number", "description": "Discount amount in cents" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "sourceType": { "type": "string", "enum": [ "promotion_code", "referral_grant" ] }, "sourceCode": { "type": "string" }, "sourceCodeId": { "type": "string" }, "sourceGrantId": { "type": "string" } }, "required": [ "promotionId", "promotionType", "category", "label", "discountAmount", "params", "sourceType" ], "additionalProperties": false } }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false } }, "required": [ "status", "appliedCode", "totalDiscount", "appliedPromotions", "quote" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "attemptedCode": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "quote": { "anyOf": [ { "type": "object", "properties": { "quoteId": { "type": "string", "description": "The quote ID -- use this to execute or retrieve the quote" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot expires" }, "refreshedAt": { "type": "string", "description": "ISO 8601 timestamp when this pricing snapshot was computed" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "fulfillmentDays": { "type": "number", "description": "Estimated fulfillment days" } }, "required": [ "sku", "title", "fulfillmentDays" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot as a percentage" }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium over spot in dollars" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant", "offer" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "optionals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fee": { "type": "number", "description": "Fee in cents" }, "selected": { "type": "boolean", "description": "Whether this optional is currently selected" }, "enabled": { "type": "boolean", "description": "Whether this optional is available for selection" }, "disabledReason": { "description": "Why this optional is unavailable", "type": "string" }, "disclaimer": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false } }, "required": [ "id", "title", "description", "fee", "selected", "enabled" ], "additionalProperties": false }, "description": "Available add-on services (e.g. instant payout)" }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "quoteId", "expiresAt", "refreshedAt", "lineItems", "fees", "optionals", "subtotal", "total" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "status", "attemptedCode", "error", "quote" ], "additionalProperties": false } ] } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/sell/quotes/{quoteId}/execute": { "post": { "summary": "Execute a sell quote", "tags": [ "Execution - Sell" ], "description": "Execute a previously created sell quote. Validates pricing, creates sell orders, and initiates payout.\n\n**Requires role:** stytch_admin\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The total from the quote response, in cents. The order is rejected if the current total is less than this value (protects against payout decreases)." }, "selectedOptionalIds": { "description": "Optional IDs to confirm (e.g. instant payout). Must match the selections from the quote.", "type": "array", "items": { "type": "string" } }, "expectedOptionalFees": { "description": "Expected per-optional fees in cents for reconciliation at confirm time", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "adjustListings": { "description": "When true, decrements the seller's active listings for the same products during checkout", "type": "boolean" }, "confirmListingMismatch": { "description": "When true, skips the error when sell quantity is less than listed quantity", "type": "boolean" }, "promotionCode": { "description": "Promotion code to apply at checkout", "type": "string" } }, "required": [ "expectedTotal" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "The quote ID (cart ID) to execute" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "orderId": { "type": "number", "description": "The main order ID" }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number", "description": "Unit price in cents" }, "total": { "type": "number", "description": "Line total in cents" }, "success": { "type": "boolean" } }, "required": [ "lineItemId", "productId", "variantId", "quantity", "price", "total", "success" ], "additionalProperties": false } }, "checkout": { "type": "object", "properties": { "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "number" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string" }, "disabled": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } }, "required": [ "sku", "title" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "id", "quantity", "price", "status", "disabled", "error", "product", "variant" ], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "id", "label", "amount" ], "additionalProperties": false } }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "total": { "type": "number", "description": "Total payout in cents" } }, "required": [ "lineItems", "fees", "subtotal", "total" ], "additionalProperties": false }, "counterpartyOrderIds": { "type": "array", "items": { "type": "number" }, "description": "Buy order IDs created as the counterparty side of this sell" } }, "required": [ "status", "orderId", "items", "checkout", "counterpartyOrderIds" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/execution/v2/trading-status": { "get": { "summary": "Get trading status", "tags": [ "Execution" ], "description": "Returns the current buy/sell trading status including active halts and scheduled closures.\n\n**Requires role:** stytch_member\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "buy": { "type": "object", "properties": { "is_open": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "halted_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "halt_type": { "anyOf": [ { "type": "string", "enum": [ "indefinite", "timed", "schedule" ] }, { "type": "null" } ] } }, "required": [ "is_open", "reason", "halted_until", "halt_type" ], "additionalProperties": false }, "sell": { "type": "object", "properties": { "is_open": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "halted_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "halt_type": { "anyOf": [ { "type": "string", "enum": [ "indefinite", "timed", "schedule" ] }, { "type": "null" } ] } }, "required": [ "is_open", "reason", "halted_until", "halt_type" ], "additionalProperties": false } }, "required": [ "buy", "sell" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/healthcheck/v1": { "get": { "summary": "Marketplace API healthcheck", "tags": [ "Root" ], "description": "Returns the health status of the Marketplace API.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "timestamp", "service" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://api.collectpure.com/", "description": "Production server" }, { "url": "https://sandbox.api.collectpure.com/", "description": "Sandbox server" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Root", "description": "API information and status" }, { "name": "Products", "description": "Enriched product endpoints \u2014 full product details, search, and catalog metadata" }, { "name": "Listings", "description": "Listing management \u2014 create, update, deactivate, list, and view statistics" }, { "name": "Offers", "description": "Offer management \u2014 create, update, deactivate, list, and view statistics" }, { "name": "Orders", "description": "Orders from Pure's fulfillment side: purchase orders are your sells (inbound to Pure), sale orders are your buys (outbound from Pure)" }, { "name": "Marketplace", "description": "Spot prices, marketplace statistics, shipping dates, and sitemap data" }, { "name": "Organization", "description": "Organization details, settings, and product watchlist management" }, { "name": "Inventory", "description": "Inventory management \u2014 view items and aggregate statistics for your organization" }, { "name": "Vault", "description": "Vault shipping \u2014 intake shipments, holdings, fulfillment, and outbound requests" }, { "name": "Vault (Alpha)", "description": "Alpha vault reads \u2014 intake address, inventory, inbound/outbound shipments, and outbound-request v2. Subject to change." }, { "name": "Products (Legacy)", "description": "Legacy product endpoints \u2014 use the enriched Products endpoints instead" }, { "name": "Listings (Legacy)", "description": "Legacy listing endpoints \u2014 use Orderbook endpoints instead" }, { "name": "Offers (Legacy)", "description": "Legacy offer endpoints \u2014 use Orderbook endpoints instead" }, { "name": "Execution - Buy", "description": "Buy execution \u2014 quotes, payment methods, and order placement" }, { "name": "Execution - Sell", "description": "Sell execution \u2014 quotes, payout methods, and order placement" }, { "name": "Execution", "description": "Execution meta \u2014 trading status and shared execution resources" }, { "name": "Sandbox", "description": "Sandbox-only endpoints for discovering test data \u2014 not available in production" } ] }