{ "openapi": "3.0.0", "info": { "title": "PuppetVendors Merchant API V2", "version": "2.0.0", "description": "The endpoints reachable with a merchant API key (`mk_live_…`), minted from Settings → API Access in the PuppetVendors admin. A merchant key administers users and vendors, and renews its own token. Everything else in the V2 API, including orders, products, payouts, fulfillments and documents, stays on the v1 API token and is refused here with a 403. Keys are revealed once at creation; rotating one leaves the previous key working for a 24 hour grace window.", "contact": { "name": "PuppetVendors Support", "url": "https://puppetvendors.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://production-api.puppetvendors.com", "description": "Production" }, { "url": "http://localhost:8082", "description": "Local development" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "apiKey", "in": "header", "name": "x-access-token", "description": "JWT minted from a merchant API key (`mk_live_…`) by POST /authenticate. Send the token value directly, with no \"Bearer\" prefix. Tokens last 14 days and can be renewed at POST /refresh-token; revoking the key refuses the next request made with any token minted from it." } }, "schemas": { "SuccessResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates the request was successful" }, "data": { "description": "The response payload" } } }, "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Indicates the request failed" }, "error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable error message", "example": "Resource not found" }, "code": { "type": "string", "description": "Stable machine-readable error code. The frontend uses this as its localisation key (e.g. errors.api.). Server errors always report INTERNAL_SERVER_ERROR.", "example": "NOT_FOUND" }, "errorId": { "type": "string", "description": "Correlation id for support/log lookup. Present on opaque 5xx responses so a user can quote a reference for the underlying (server-side logged) error.", "example": "err_1783365360839_j281w7b" }, "details": { "type": "object", "description": "Additional client-error context (e.g. field-level validation errors). Never populated for server errors." } } } } }, "PaginationInput": { "type": "object", "properties": { "first": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return (forward pagination)", "example": 20 }, "after": { "type": "string", "description": "Cursor for forward pagination (from previous page endCursor)", "example": "eyJpZCI6IjY3ODkwIn0=" }, "last": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return (backward pagination)", "example": 20 }, "before": { "type": "string", "description": "Cursor for backward pagination (from previous page startCursor)", "example": "eyJpZCI6IjEyMzQ1In0=" } } }, "PayoutAdjustment": { "type": "object", "properties": { "_id": { "type": "string", "description": "Adjustment id", "example": "6aa7bfa25133067f0da9c0f1" }, "shopId": { "type": "string", "description": "The shop this adjustment belongs to" }, "vendorId": { "type": "string", "description": "The vendor whose payout this adjusts" }, "vendorName": { "type": "string", "description": "The vendor's name, copied onto the row when it is created. A later rename of the vendor does not rewrite it." }, "amount": { "type": "number", "description": "SIGNED, and this is the field integrators most often get wrong. You always SEND a positive amount plus a type; what is stored and returned carries the sign taken from that type, so a DEDUCTION of 25 reads back as -25 and an ADDITION of 25 as 25. Summing this field over a vendor gives the net effect on their payout with no further interpretation.", "example": -25 }, "type": { "type": "string", "enum": [ "ADDITION", "DEDUCTION" ], "description": "Whether this adds to or deducts from the payout. Determines the sign of `amount`." }, "status": { "type": "string", "enum": [ "UNPAID", "PAID" ], "description": "Owned by the payout engine, never settable through this API. UNPAID until a payout batch includes it, PAID afterwards. A PAID adjustment is frozen: editing or deleting it returns 409." }, "batchId": { "type": "string", "description": "The payout batch that paid this adjustment, or the string \"NA\" while it is still unpaid. Owned by the payout engine.", "example": "NA" }, "customId": { "type": "string", "description": "Server-generated display reference, shown as the row identifier on payout statements and CSV exports. Generated per row and not settable by the caller.", "example": "G6TTITU3S1" }, "comments": { "type": "string", "description": "Free-text note from the caller" }, "customItemDate": { "type": "string", "format": "date-time", "description": "The date the adjustment applies to, which decides the payout period it falls in. Defaults to the moment of creation when omitted." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PayoutAdjustmentResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PayoutAdjustment" } } }, "PayoutAdjustmentListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutAdjustment" } }, "total": { "type": "integer", "description": "Total adjustments matching the filter, across all pages" }, "page": { "type": "integer", "description": "The page returned, 1-based" }, "limit": { "type": "integer", "description": "Page size used" } } } } }, "PageInfo": { "type": "object", "required": [ "hasNextPage", "hasPreviousPage" ], "properties": { "hasNextPage": { "type": "boolean", "description": "Whether there are more items after the current page" }, "hasPreviousPage": { "type": "boolean", "description": "Whether there are more items before the current page" }, "startCursor": { "type": "string", "description": "Cursor for the first item in the page", "nullable": true }, "endCursor": { "type": "string", "description": "Cursor for the last item in the page", "nullable": true }, "totalCount": { "type": "integer", "description": "Total number of items (may not always be available)", "nullable": true } } }, "OrderListItem": { "type": "object", "required": [ "_id", "orderId", "orderName", "orderNumber", "createdAt", "totalQuantity", "lineItemCount", "totalSales", "totalNetSales", "totalCostOfItem", "totalProfit", "totalCommission", "totalPayout", "status", "fulfillmentStatus", "vendorPayoutStatus", "financialStatus" ], "properties": { "_id": { "type": "string", "description": "Order ObjectId", "example": "507f1f77bcf86cd799439014" }, "orderId": { "type": "integer", "description": "Shopify numeric order id", "example": 450789469 }, "orderName": { "type": "string", "description": "Order name (e.g. #1001)", "example": "#1001" }, "orderNumber": { "type": "integer", "description": "Sequential order number", "example": 1001 }, "createdAt": { "type": "string", "format": "date-time", "description": "Order creation timestamp (ISO 8601)" }, "totalQuantity": { "type": "number", "description": "Total quantity across the vendor's line items on this order" }, "lineItemCount": { "type": "number", "description": "Number of the vendor's line items on this order" }, "totalSales": { "type": "number", "description": "Gross sales for the vendor's line items", "example": 99.99 }, "totalNetSales": { "type": "number", "description": "Net sales after discounts" }, "totalCostOfItem": { "type": "number", "description": "Total cost of goods for the vendor items" }, "totalProfit": { "type": "number", "description": "Profit (net sales minus cost of items)" }, "totalCommission": { "type": "number", "description": "Commission charged on the vendor items" }, "totalPayout": { "type": "number", "description": "Amount payable to the vendor for this order", "example": 42.49 }, "status": { "type": "array", "items": { "type": "string" }, "description": "Distinct per-line fulfillment statuses on the order", "example": [ "fulfilled" ] }, "fulfillmentStatus": { "type": "string", "description": "Rolled-up fulfillment status for the vendor items", "example": "fulfilled" }, "vendorPayoutStatus": { "type": "string", "enum": [ "paid", "unpaid", "partial" ], "description": "Vendor payout status for this order" }, "financialStatus": { "type": "string", "description": "Payment/financial status", "example": "paid" }, "shipDate": { "type": "string", "format": "date-time", "description": "Ship date, if set" }, "deliveryDate": { "type": "string", "format": "date-time", "description": "Delivery date, if set" }, "notes": { "type": "string", "description": "Free-text order notes" }, "customer": { "type": "object", "description": "Customer summary (subject to PII visibility rules)", "properties": { "email": { "type": "string", "description": "Customer email" }, "first_name": { "type": "string", "description": "Customer first name" }, "last_name": { "type": "string", "description": "Customer last name" } } } } }, "OrderListResponse": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItem" }, "description": "The page of orders matching the query" }, "totalCount": { "type": "integer", "description": "Total number of matching orders across all pages" }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } }, "AuthenticateRequest": { "type": "object", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string", "description": "Shop's openApiToken for authentication", "example": "sk_live_abc123def456" }, "shopDomain": { "type": "string", "description": "Optional shop domain (V1 compatibility). When provided, must match the shop for the apiKey.", "example": "my-store.myshopify.com" }, "vendorId": { "type": "string", "description": "Optional vendor ObjectId for vendor-scoped token", "example": "507f1f77bcf86cd799439011" } } }, "AuthenticateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT token for API authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "expiresIn": { "type": "integer", "description": "Token expiry time in seconds", "example": 1209600 }, "scope": { "type": "string", "enum": [ "merchant", "vendor" ], "description": "Token scope indicating access level" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Optional list of coarse-grained permissions granted to this token (e.g., admin:users, admin:vendors). When omitted, the token has full access for its scope." }, "shopDomain": { "type": "string", "description": "Shop domain (included for V1 API compatibility)", "example": "my-store.myshopify.com" }, "vendorId": { "type": "string", "description": "Vendor ID — only present for vendor-scope tokens (when authenticating with a `vk_*` vendor key). Identifies which vendor the public API call originates from.", "example": "507f1f77bcf86cd799439011" }, "vendorEmail": { "type": "string", "description": "Vendor reporting email — only present for vendor-scope tokens when the vendor has a reportingEmail set. Useful for confirming which vendor account the key belongs to.", "example": "vendor@example.com" } } } } }, "RefreshTokenResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "New JWT token" }, "expiresIn": { "type": "integer", "description": "Token expiry time in seconds", "example": 1209600 }, "shopDomain": { "type": "string", "description": "Shop domain (included for V1 API compatibility)", "example": "my-store.myshopify.com" } } } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } }, "Vendor": { "type": "object", "properties": { "_id": { "type": "string", "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Vendor name", "example": "Acme Corporation" }, "alias": { "type": "string", "description": "Vendor alias/short name", "example": "acme" }, "email": { "type": "string", "format": "email", "description": "Vendor email address", "example": "vendor@acme.com" }, "commissionType": { "type": "string", "enum": [ "percentage", "flat" ], "description": "Commission type", "example": "percentage" }, "commissionRate": { "type": "number", "description": "Commission rate (percentage or flat amount)", "example": 15 }, "isHidden": { "type": "boolean", "description": "Whether vendor is hidden", "example": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "User": { "type": "object", "properties": { "_id": { "type": "string", "description": "User ObjectId", "example": "507f1f77bcf86cd799439012" }, "email": { "type": "string", "format": "email", "description": "User email address", "example": "user@example.com" }, "name": { "type": "string", "description": "User full name", "example": "John Doe" }, "type": { "type": "string", "enum": [ "vendor", "merchant", "admin" ], "description": "User type", "example": "vendor" }, "vendorId": { "type": "string", "description": "Associated vendor ObjectId (for vendor users)", "example": "507f1f77bcf86cd799439011" }, "approved": { "type": "boolean", "description": "Whether user is approved", "example": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Product": { "type": "object", "properties": { "_id": { "type": "string", "description": "Product ObjectId", "example": "507f1f77bcf86cd799439013" }, "title": { "type": "string", "description": "Product title", "example": "Widget Pro" }, "handle": { "type": "string", "description": "URL-friendly product handle", "example": "widget-pro" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "description": "Product status", "example": "active" }, "vendorId": { "type": "string", "description": "Associated vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Mongo subdocument id" }, "id": { "type": "string", "description": "Shopify variant id (numeric) once synced" }, "admin_graphql_api_id": { "type": "string", "description": "Shopify variant GID once synced" }, "title": { "type": "string", "description": "Variant title (e.g. \"Red / Large\")" }, "sku": { "type": "string" }, "price": { "type": "number" }, "inventory": { "type": "number" }, "optionValues": { "type": "array", "description": "Resolved option name/value pairs", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "selectedOptions": { "type": "array", "description": "Shopify-shaped option name/value pairs", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "inventoryQuantities": { "type": "array", "description": "Per-location stock for this variant", "items": { "type": "object", "properties": { "locationId": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "availableQuantity": { "type": "integer" } } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Order": { "type": "object", "properties": { "_id": { "type": "string", "description": "Order ObjectId", "example": "507f1f77bcf86cd799439014" }, "name": { "type": "string", "description": "Order name (e.g., #1001)", "example": "#1001" }, "orderNumber": { "type": "integer", "description": "Numeric order number", "example": 1001 }, "financialStatus": { "type": "string", "description": "Payment status", "example": "paid" }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status", "example": "fulfilled" }, "totalPrice": { "type": "number", "description": "Order total", "example": 99.99 }, "createdAt": { "type": "string", "format": "date-time" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } } } }, "LineItem": { "type": "object", "properties": { "_id": { "type": "string", "description": "Line item ObjectId", "example": "507f1f77bcf86cd799439015" }, "name": { "type": "string", "description": "Line item name", "example": "Widget Pro - Large" }, "sku": { "type": "string", "description": "Stock keeping unit", "example": "WIDGET-L" }, "quantity": { "type": "integer", "description": "Quantity ordered", "example": 2 }, "price": { "type": "number", "description": "Unit price", "example": 49.99 }, "vendorId": { "type": "string", "description": "Associated vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status of this line item", "example": "fulfilled" }, "vendorPayout": { "type": "number", "description": "Vendor payout amount", "example": 42.49 } } }, "Payout": { "type": "object", "properties": { "_id": { "type": "string", "description": "Line item ObjectId (payout record)", "example": "507f1f77bcf86cd799439015" }, "orderName": { "type": "string", "description": "Order name", "example": "#1001" }, "lineItemName": { "type": "string", "description": "Line item name", "example": "Widget Pro - Large" }, "sku": { "type": "string", "description": "SKU", "example": "WIDGET-L" }, "quantity": { "type": "integer", "description": "Quantity", "example": 2 }, "sales": { "type": "number", "description": "Sales amount", "example": 99.98 }, "commission": { "type": "number", "description": "Commission amount", "example": 15 }, "payout": { "type": "number", "description": "Payout amount", "example": 84.98 }, "paid": { "type": "boolean", "description": "Whether paid", "example": false }, "fulfilled": { "type": "boolean", "description": "Whether fulfilled", "example": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "Fulfillment": { "type": "object", "properties": { "_id": { "type": "string", "description": "Line item ObjectId", "example": "507f1f77bcf86cd799439015" }, "orderName": { "type": "string", "description": "Order name", "example": "#1001" }, "lineItemName": { "type": "string", "description": "Line item name", "example": "Widget Pro - Large" }, "sku": { "type": "string", "description": "SKU", "example": "WIDGET-L" }, "quantity": { "type": "integer", "description": "Quantity", "example": 2 }, "fulfillmentStatus": { "type": "string", "enum": [ "fulfilled", "unfulfilled", "partial", "restocked" ], "description": "Fulfillment status", "example": "unfulfilled" }, "trackingNumber": { "type": "string", "description": "Tracking number", "example": "1Z999AA10123456784" }, "trackingUrl": { "type": "string", "format": "uri", "description": "Tracking URL", "example": "https://tracking.example.com/1Z999AA10123456784" }, "shippingCarrier": { "type": "string", "description": "Shipping carrier", "example": "UPS" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Commission": { "type": "object", "properties": { "_id": { "type": "string", "description": "Commission ObjectId", "example": "507f1f77bcf86cd799439016" }, "sku": { "type": "string", "description": "SKU", "example": "WIDGET-L" }, "rate": { "type": "number", "description": "Commission rate", "example": 15 }, "type": { "type": "string", "enum": [ "percentage", "flat" ], "description": "Commission type", "example": "percentage" }, "productId": { "type": "string", "description": "Associated product ObjectId", "example": "507f1f77bcf86cd799439013" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PaginatedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": {}, "description": "Array of items" }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } } }, "CreateFulfillmentRequest": { "type": "object", "required": [ "lineItemIds" ], "properties": { "trackingNumber": { "type": "string", "description": "Tracking number for the shipment (optional)", "example": "1Z999AA10123456784" }, "shippingCarrier": { "type": "string", "description": "Name of the shipping carrier (optional)", "example": "UPS" }, "trackingUrl": { "type": "string", "format": "uri", "description": "URL to track the shipment (optional)", "example": "https://www.ups.com/track?tracknum=1Z999AA10123456784" }, "lineItemIds": { "type": "array", "items": { "type": "string" }, "description": "Array of line item ObjectIds to fulfill", "example": [ "507f1f77bcf86cd799439015", "507f1f77bcf86cd799439016" ] }, "notifyCustomer": { "type": "boolean", "description": "Whether to send shipping notification to customer", "example": true } } }, "CreateFulfillmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the fulfillment was created successfully" }, "fulfillmentsCreated": { "type": "integer", "description": "Number of fulfillments created", "example": 2 }, "shopifyFulfillmentId": { "type": "string", "description": "Shopify fulfillment ID", "example": "gid://shopify/Fulfillment/123456" } } } } }, "VendorRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Vendor name", "example": "Acme Corporation" }, "alias": { "type": "string", "description": "Vendor alias/short name", "example": "acme" }, "email": { "type": "string", "format": "email", "description": "Vendor email address", "example": "vendor@acme.com" }, "commissionType": { "type": "string", "enum": [ "percentage", "flat" ], "description": "Commission type", "example": "percentage" }, "commissionRate": { "type": "number", "description": "Commission rate", "example": 15 }, "isHidden": { "type": "boolean", "description": "Whether vendor is hidden", "example": false } } }, "UserRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "User email address", "example": "user@example.com" }, "name": { "type": "string", "description": "User full name", "example": "John Doe" }, "password": { "type": "string", "format": "password", "description": "User password", "example": "securePassword123" }, "type": { "type": "string", "enum": [ "vendor", "merchant", "admin" ], "description": "User type", "example": "vendor" }, "vendorId": { "type": "string", "description": "Associated vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "approved": { "type": "boolean", "description": "Whether user is approved", "example": true } } }, "SkuCommissionBulkRequest": { "type": "object", "required": [ "commissions" ], "properties": { "commissions": { "type": "array", "maxItems": 500, "items": { "type": "object", "required": [ "sku", "rate", "type" ], "properties": { "sku": { "type": "string", "description": "Stock keeping unit", "example": "WIDGET-L" }, "rate": { "type": "number", "description": "Commission rate", "example": 15 }, "type": { "type": "string", "enum": [ "percentage", "flat" ], "description": "Commission type", "example": "percentage" } } } } } }, "LineItemsBulkUpdateRequest": { "type": "object", "required": [ "updates" ], "properties": { "updates": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "lineItemId" ], "properties": { "lineItemId": { "type": "string", "description": "Line item ObjectId to update", "example": "507f1f77bcf86cd799439015" }, "vendorId": { "type": "string", "description": "New vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "description": "New status", "example": "active" }, "ignoreInPayout": { "type": "boolean", "description": "Whether to ignore in payout calculations", "example": false } } } } } }, "PayoutSummaryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "totalSales": { "type": "number", "description": "Total sales amount", "example": 9999.99 }, "totalCommission": { "type": "number", "description": "Total commission amount", "example": 1500 }, "totalPayout": { "type": "number", "description": "Total payout amount", "example": 8499.99 }, "paidAmount": { "type": "number", "description": "Amount already paid", "example": 5000 }, "unpaidAmount": { "type": "number", "description": "Amount unpaid", "example": 3499.99 }, "itemCount": { "type": "integer", "description": "Number of line items", "example": 150 } } } } }, "ReportSummaryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "totalOrders": { "type": "integer", "description": "Total number of orders", "example": 50 }, "totalSales": { "type": "number", "description": "Total sales amount", "example": 9999.99 }, "totalCommission": { "type": "number", "description": "Total commission amount", "example": 1500 }, "totalPayout": { "type": "number", "description": "Total payout amount", "example": 8499.99 }, "itemsSold": { "type": "integer", "description": "Total items sold", "example": 150 } } } } }, "ShopProfileConfigResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "profileSetup": { "type": "boolean", "description": "Whether profile setup is enabled", "example": true }, "termsAndConditions": { "type": "object", "description": "Terms and conditions configuration" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "visible": { "type": "boolean" }, "editable": { "type": "boolean" } } } }, "publicDisplay": { "type": "object", "description": "Public display configuration" }, "hideLogin": { "type": "boolean", "description": "Whether login is hidden" }, "hideSignup": { "type": "boolean", "description": "Whether signup is hidden" } } } } }, "VendorLoginRequest": { "type": "object", "required": [ "email", "password", "shopDomain" ], "properties": { "email": { "type": "string", "format": "email", "description": "Vendor user email address", "example": "vendor@example.com" }, "password": { "type": "string", "format": "password", "description": "Vendor user password", "example": "secret123" }, "shopDomain": { "type": "string", "description": "Shop domain", "example": "my-store.myshopify.com" } } }, "VendorLoginResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT token for API authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "expiresIn": { "type": "integer", "description": "Token expiry time in seconds", "example": 1209600 }, "scope": { "type": "string", "enum": [ "vendor" ], "description": "Token scope" }, "shopDomain": { "type": "string", "description": "Shop domain", "example": "my-store.myshopify.com" }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ObjectId", "example": "507f1f77bcf86cd799439011" }, "email": { "type": "string", "format": "email", "description": "User email", "example": "vendor@example.com" }, "vendorId": { "type": "string", "description": "Associated vendor ObjectId", "example": "507f1f77bcf86cd799439012" }, "vendor": { "type": "string", "description": "Vendor name", "example": "Acme Co" }, "profile": { "type": "object", "properties": { "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Smith" }, "phone": { "type": "string", "example": "+1-555-123-4567" } } } } } } } } }, "ProductOptionInput": { "type": "object", "required": [ "name", "values" ], "properties": { "name": { "type": "string", "description": "Option name (e.g., Color, Size)", "example": "Color" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Possible values for this option", "example": [ "Red", "Blue", "Green" ] } } }, "ProductVariantInput": { "type": "object", "properties": { "optionValues": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Color" }, "value": { "type": "string", "example": "Red" } } }, "description": "Option values for this variant" }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "description": "Variant price", "example": "29.99" }, "compareAtPrice": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "description": "Original/compare price", "example": "39.99" }, "sku": { "type": "string", "maxLength": 255, "description": "Stock keeping unit", "example": "WIDGET-RED-L" }, "barcode": { "type": "string", "maxLength": 255, "description": "EAN/barcode" }, "inventoryQuantity": { "type": "integer", "minimum": -1000000000, "maximum": 1000000000, "description": "Inventory quantity at location. May be negative for oversold or backordered stock, which only actually sells when the variant inventoryPolicy is CONTINUE.", "example": 100 }, "locationId": { "type": "string", "description": "Shopify location ID (required if inventoryQuantity is provided)", "example": "gid://shopify/Location/123456" }, "requiresShipping": { "type": "boolean", "description": "Whether variant requires shipping", "example": true }, "taxable": { "type": "boolean", "description": "Whether variant is taxable", "example": true }, "inventoryPolicy": { "type": "string", "enum": [ "DENY", "CONTINUE" ], "description": "Behavior when out of stock", "example": "DENY" } } }, "ProductMetafieldInput": { "type": "object", "required": [ "namespace", "key", "value" ], "properties": { "namespace": { "type": "string", "description": "Metafield namespace", "example": "custom" }, "key": { "type": "string", "description": "Metafield key", "example": "color_family" }, "value": { "type": "string", "description": "Metafield value", "example": "red" }, "type": { "type": "string", "description": "Metafield type", "example": "single_line_text_field" }, "description": { "type": "string", "description": "Metafield description" } } }, "ProductMediaInput": { "type": "object", "required": [ "originalSource" ], "properties": { "originalSource": { "type": "string", "format": "uri", "description": "URL to the media file", "example": "https://cdn.example.com/product-image.jpg" }, "mediaContentType": { "type": "string", "enum": [ "IMAGE", "VIDEO", "MODEL_3D", "EXTERNAL_VIDEO" ], "description": "Type of media", "example": "IMAGE" }, "alt": { "type": "string", "maxLength": 255, "description": "Alt text for accessibility", "example": "Red widget product image" } } }, "SeoInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "SEO title tag", "example": "Premium Widget - Best Price Online" }, "description": { "type": "string", "maxLength": 320, "description": "SEO meta description", "example": "High-quality widgets at competitive prices. Free shipping on orders over $50." } } }, "ProductCreateRequest": { "type": "object", "required": [ "title", "vendorId" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Product title", "example": "Widget Pro Deluxe" }, "descriptionHtml": { "type": "string", "description": "Product description in HTML", "example": "

Premium widget with advanced features

" }, "vendorId": { "type": "string", "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "productType": { "type": "string", "maxLength": 255, "description": "Product type/category", "example": "Widgets" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 250, "description": "Product tags", "example": [ "premium", "bestseller", "new" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Product status", "example": "DRAFT" }, "handle": { "type": "string", "maxLength": 255, "description": "URL-friendly product handle", "example": "widget-pro-deluxe" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" }, "maxItems": 3, "description": "Product options (e.g., Color, Size)" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantInput" }, "maxItems": 100, "description": "Product variants" }, "metafields": { "type": "array", "items": { "$ref": "#/components/schemas/ProductMetafieldInput" }, "description": "Custom metafields" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/ProductMediaInput" }, "maxItems": 250, "description": "Product media (images, videos, etc.)" }, "seo": { "$ref": "#/components/schemas/SeoInput", "description": "SEO settings" }, "category": { "type": "string", "description": "Product category/collection", "example": "Electronics" }, "templateSuffix": { "type": "string", "description": "Custom template suffix" }, "published": { "type": "boolean", "description": "Whether product is visible to customers", "example": false } } }, "ProductUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Product title", "example": "Widget Pro Deluxe v2" }, "descriptionHtml": { "type": "string", "description": "Product description in HTML" }, "vendorId": { "type": "string", "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, "productType": { "type": "string", "maxLength": 255, "description": "Product type/category" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 250, "description": "Product tags (replaces existing)" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Product status" }, "handle": { "type": "string", "maxLength": 255, "description": "URL-friendly product handle" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" }, "maxItems": 3, "description": "Product options (replaces existing)" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantInput" }, "maxItems": 100, "description": "Product variants (replaces existing)" }, "metafields": { "type": "array", "items": { "$ref": "#/components/schemas/ProductMetafieldInput" }, "description": "Custom metafields (replaces existing)" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/ProductMediaInput" }, "maxItems": 250, "description": "Product media (replaces existing)" }, "seo": { "$ref": "#/components/schemas/SeoInput", "description": "SEO settings" }, "category": { "type": "string", "description": "Product category/collection" }, "templateSuffix": { "type": "string", "description": "Custom template suffix" }, "published": { "type": "boolean", "description": "Whether product is visible to customers" } } }, "ProductInventoryUpdateRequest": { "type": "object", "required": [ "variants" ], "properties": { "variants": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Per variant × location quantity updates", "items": { "type": "object", "required": [ "variantId", "locationId", "quantity" ], "properties": { "variantId": { "type": "string", "description": "Shopify variant id, GID, or local subdocument id" }, "locationId": { "type": "string", "description": "Location id the quantity applies to" }, "quantity": { "type": "integer", "minimum": -2000000000, "maximum": 2000000000, "description": "Absolute target in set mode (-1000000000 to 1000000000; may be negative for oversold stock) or a signed delta in adjust mode (-2000000000 to 2000000000). The narrower set-mode range is enforced per request." }, "inventoryItemId": { "type": "string", "description": "Optional; derived from the variant when omitted" }, "compareQuantity": { "type": "integer", "description": "Current quantity for optimistic-lock conflict detection" } } } }, "mode": { "type": "string", "enum": [ "set", "adjust" ], "default": "set", "description": "set = absolute quantity; adjust = delta" }, "reason": { "type": "string", "maxLength": 255, "description": "Optional audit reason" } } }, "ProductMediaUploadRequest": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "description": "Base64-encoded file content or a reachable HTTP(S) URL" }, "filename": { "type": "string", "maxLength": 255, "description": "Original filename (used to infer type for raw base64)" }, "mediaContentType": { "type": "string", "enum": [ "IMAGE", "VIDEO", "MODEL_3D", "EXTERNAL_VIDEO" ], "default": "IMAGE", "description": "Declared media type; non-IMAGE goes to Shopify staging" }, "alt": { "type": "string", "maxLength": 255, "description": "Alt text" } } }, "CSVBoxRow": { "type": "object", "required": [ "Handle", "Title" ], "additionalProperties": { "type": "string" }, "properties": { "Handle": { "type": "string", "description": "Product handle (groups variant rows)" }, "Title": { "type": "string", "description": "Product title" }, "Description": { "type": "string" }, "Vendor": { "type": "string" }, "Type": { "type": "string" }, "Tags": { "type": "string" }, "Variant SKU": { "type": "string" }, "Variant Price": { "type": "string" }, "Variant Compare At Price": { "type": "string" }, "Variant Inventory Policy": { "type": "string", "enum": [ "continue", "deny" ] }, "Variant Requires Shipping": { "type": "string", "enum": [ "true", "false" ] }, "Variant Taxable": { "type": "string", "enum": [ "true", "false" ] }, "Variant Barcode": { "type": "string" }, "Variant Weight": { "type": "string" }, "Variant Weight Unit": { "type": "string", "enum": [ "GRAMS", "KILOGRAMS", "OUNCES", "POUNDS" ] }, "Option1 Name": { "type": "string" }, "Option1 Value": { "type": "string" }, "Option2 Name": { "type": "string" }, "Option2 Value": { "type": "string" }, "Option3 Name": { "type": "string" }, "Option3 Value": { "type": "string" }, "Image Src": { "type": "string" }, "Image Alt Text": { "type": "string" }, "Cost Per Item": { "type": "string" }, "Variant Fulfillment Service": { "type": "string" }, "Variant Tax Code": { "type": "string" }, "Gift Card": { "type": "string", "enum": [ "true", "false" ] }, "Image Position": { "type": "string" }, "Track Quantity": { "type": "string", "enum": [ "true", "false" ] }, "Published": { "type": "string", "enum": [ "true", "false" ] } } }, "VendorProfile": { "type": "object", "properties": { "companyName": { "type": "string", "example": "Acme Corporation" }, "phone": { "type": "string", "example": "+1-555-123-4567" }, "email": { "type": "string", "format": "email", "example": "vendor@acme.com" }, "website": { "type": "string", "format": "uri", "example": "https://acme.com" }, "taxId": { "type": "string", "example": "12-3456789" }, "vatNumber": { "type": "string", "example": "GB123456789" }, "about": { "type": "string", "example": "Leading widget manufacturer" }, "logo": { "type": "string", "example": "https://cdn.example.com/logo.png" } } }, "VendorAddress": { "type": "object", "properties": { "address1": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Suite 100" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "10001" }, "phone": { "type": "string", "example": "+1-555-123-4567" } } }, "VendorProfileUpdate": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Profile field name" }, "value": { "description": "Field value (any type)" } } } } } }, "VendorAddressUpdate": { "type": "object", "properties": { "address1": { "type": "string", "maxLength": 500 }, "address2": { "type": "string", "maxLength": 500 }, "city": { "type": "string", "maxLength": 200 }, "state": { "type": "string", "maxLength": 200 }, "country": { "type": "string", "maxLength": 200 }, "zip": { "type": "string", "maxLength": 50 }, "phone": { "type": "string", "maxLength": 50 } } } } }, "tags": [ { "name": "Auth", "description": "Authentication endpoints for obtaining and refreshing API tokens" }, { "name": "Portal - Auth", "description": "Vendor portal authentication endpoints (vendor user login, token refresh)" }, { "name": "Products", "description": "Product management and synchronization" }, { "name": "Orders", "description": "Order retrieval and management" }, { "name": "Payouts", "description": "Vendor payout information" }, { "name": "Fulfillments", "description": "Order fulfillment operations" }, { "name": "Reports", "description": "Vendor sales reports and analytics" }, { "name": "Vendors", "description": "Vendor management operations" }, { "name": "Settings", "description": "Settings endpoints for vendor configuration and management" }, { "name": "Users", "description": "User account management" }, { "name": "Shop", "description": "Shop configuration and settings" }, { "name": "Commissions", "description": "Commission rate management" }, { "name": "Integrations", "description": "Vendor integration configuration endpoints" }, { "name": "Line Items", "description": "Order line item operations" } ], "paths": { "/authenticate": { "post": { "tags": [ "Auth" ], "summary": "Authenticate and get API token", "description": "Authenticate using an API key to obtain a JWT token.\nThe key's prefix determines the token scope:\n- **Merchant key** (`mk_live_…` / `mk_test_…`, from Settings → API Access):\n returns a merchant-scoped token with full access. Named, rotatable and\n revocable per integration.\n- **Vendor key** (`vk_live_…` / `vk_test_…`, from the vendor portal):\n returns a vendor-scoped token limited to that vendor's data, carrying\n the scopes declared on the key.\n\nA rotated key keeps working until the end of its grace window, so a\nrotation is an overlap rather than a cutover.\n", "operationId": "authenticate", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateRequest" }, "examples": { "merchant": { "summary": "Authenticate with a merchant key", "value": { "apiKey": "mk_live_9f2ac1b0e7d84a3c5b1f6e8d0a2c4b6f8e0d2c4b6a8f0e2d4c6b8a0f2e4d6c8b" } }, "vendor": { "summary": "Authenticate with a vendor key", "value": { "apiKey": "vk_live_xyz789ghi012" } } } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateResponse" }, "example": { "success": true, "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 1209600, "scope": "merchant", "shopDomain": "my-store.myshopify.com" } } } } }, "401": { "description": "Invalid API key or inactive shop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "message": "Invalid API key", "code": "UNAUTHORIZED" } } } } } } } }, "/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify an API key reaches the service", "description": "Pure probe — confirms the key is valid and reachable, returns the\nscopes/mode/identity it carries, but does NOT issue a JWT or count\nas a use (lastUsedAt unchanged).\n\nSame lookup as `/authenticate`, so any key that passes here will also\npass `/authenticate`. Useful when an integration wants a side-effect-free\n\"is my key good?\" check without minting a token.\n\nAccepts the same keys `/authenticate` does: a merchant `mk_` key or a\nvendor `vk_` key. For a merchant key the reply carries\n`scope: merchant` and the key's label, and no `vendorId`.\n\nA revoked key is refused with the same 401 and the same message as a key\nthat never existed, so this cannot be used to probe which keys once\nexisted. A key inside its rotation grace window is still valid here.\n", "operationId": "verify", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateRequest" }, "examples": { "merchant": { "summary": "Confirm a merchant key", "value": { "apiKey": "mk_live_9f2ac1b0e7d84a3c5b1f6e8d0a2c4b6f8e0d2c4b6a8f0e2d4c6b8a0f2e4d6c8b" } }, "vendor": { "summary": "Confirm a vendor key", "value": { "apiKey": "vk_live_xyz789ghi012" } } } } } }, "responses": { "200": { "description": "Key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true }, "scope": { "type": "string", "enum": [ "merchant", "vendor" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "keyLabel": { "type": "string" }, "shopDomain": { "type": "string" }, "vendorId": { "type": "string" }, "vendorEmail": { "type": "string" } } } } }, "example": { "success": true, "data": { "valid": true, "scope": "vendor", "permissions": [ "orders:read", "products:read" ], "mode": "live", "keyLabel": "Zapier", "shopDomain": "my-store.myshopify.com", "vendorId": "507f1f77bcf86cd799439011", "vendorEmail": "vendor@example.com" } } } } }, "401": { "description": "Invalid API key, revoked key, or inactive shop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "message": "Invalid API key", "code": "UNAUTHORIZED" } } } } } } } }, "/refresh-token": { "post": { "tags": [ "Auth" ], "summary": "Refresh API token", "description": "Exchange a valid (non-expired) token for a new one with extended expiry.\nUse this to maintain sessions without requiring re-authentication.\n\n**Token input**:\n- Header: `x-access-token: `\n", "operationId": "refreshToken", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenResponse" }, "example": { "success": true, "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 1209600, "shopDomain": "my-store.myshopify.com" } } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payouts/adjustments": { "post": { "tags": [ "Payouts" ], "summary": "Create a payout adjustment", "description": "Create a manual payout adjustment (addition or deduction) for a vendor.\n**Merchant scope only**, requires the `admin:payouts` permission.\n\n`amount` is always positive; the stored sign is derived from `type`.\n`status` and `batchId` are owned by the payout engine and cannot be\nset by the caller.\n\nThis endpoint is **not** idempotent: every accepted request creates a\nnew adjustment, so a retried or duplicated POST creates a second one.\nCallers are responsible for not re-posting a request that may already\nhave been applied.\n", "operationId": "createPayoutAdjustment", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vendorId", "amount", "type" ], "properties": { "vendorId": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "amount": { "type": "number", "description": "Always positive; the sign comes from `type`.", "example": 25.5 }, "type": { "type": "string", "enum": [ "ADDITION", "DEDUCTION" ] }, "comments": { "type": "string" }, "date": { "type": "string", "format": "date-time", "description": "The date this adjustment applies to, which decides the payout period it lands in. Defaults to now when omitted. Returned as `customItemDate`, the stored field name." } } } } } }, "responses": { "201": { "description": "Adjustment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAdjustmentResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - merchant scope with admin:payouts required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found for this shop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Payouts" ], "summary": "List payout adjustments", "description": "Retrieve a paginated list of payout adjustments for the shop.\n**Merchant scope only**, requires the `admin:payouts` permission.\n", "operationId": "listPayoutAdjustments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "vendorId", "schema": { "type": "string" }, "description": "Filter by vendor ObjectId" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "UNPAID", "PAID" ] } }, { "in": "query", "name": "dateFrom", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "dateTo", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "List of payout adjustments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAdjustmentListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - merchant scope with admin:payouts required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payouts/adjustments/{id}": { "get": { "tags": [ "Payouts" ], "summary": "Get a payout adjustment", "description": "Retrieve a single payout adjustment by ObjectId. **Merchant scope only**, requires the `admin:payouts` permission.", "operationId": "getPayoutAdjustment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439012" } ], "responses": { "200": { "description": "Adjustment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAdjustmentResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - merchant scope with admin:payouts required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Adjustment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Payouts" ], "summary": "Update a payout adjustment", "description": "Update a payout adjustment. **Merchant scope only**, requires the\n`admin:payouts` permission. `amount` and `type` must be changed\ntogether, because the stored sign is derived from both; the request\nschema enforces that pairing. Refused once the adjustment has been\npaid or deleted.\n", "operationId": "updatePayoutAdjustment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439012" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string" }, "amount": { "type": "number" }, "type": { "type": "string", "enum": [ "ADDITION", "DEDUCTION" ] }, "comments": { "type": "string" }, "date": { "type": "string", "format": "date-time", "description": "The date this adjustment applies to. Returned as `customItemDate`, the stored field name." } } } } } }, "responses": { "200": { "description": "Adjustment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAdjustmentResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - merchant scope with admin:payouts required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Adjustment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Adjustment is paid or deleted and can no longer be modified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Payouts" ], "summary": "Delete a payout adjustment", "description": "Hard-delete a payout adjustment, at parity with legacy. **Merchant\nscope only**, requires the `admin:payouts` permission. Refused once\nthe adjustment has been paid or deleted.\n", "operationId": "deletePayoutAdjustment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439012" } ], "responses": { "204": { "description": "Adjustment deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - merchant scope with admin:payouts required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Adjustment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Adjustment is paid or deleted and can no longer be modified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "Retrieve a paginated list of users, filterable by vendor, type and\napproval status.\n\nTwo token scopes reach this path. A **merchant** token lists every\nuser on the shop and may narrow the result with `vendorId`. A\n**vendor** token is confined to its own vendor's users, and `vendorId`\nis ignored rather than honoured.\n", "operationId": "listUsers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "vendorId", "schema": { "type": "string" }, "description": "Filter by vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "vendor", "staff", "merchant", "admin" ] }, "description": "Filter by user type" }, { "in": "query", "name": "approved", "schema": { "type": "boolean" }, "description": "Filter by approval status" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search in email and vendor name" }, { "in": "query", "name": "first", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return (forward pagination)" }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor for forward pagination" }, { "in": "query", "name": "last", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return (backward pagination)" }, { "in": "query", "name": "before", "schema": { "type": "string" }, "description": "Cursor for backward pagination" } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the token is neither merchant- nor vendor-scoped, or a merchant token lacks the `admin:users` permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Users" ], "summary": "Create a new user", "description": "Create a new user account.\n\nA **merchant** token may create any user type and assign `vendorId`\nfreely. A **vendor** token creates only users of type `vendor`, owned\nby its own vendor: `vendorId` is not accepted in the body.\n", "operationId": "createUser", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRequest" }, "example": { "email": "user@example.com", "name": "John Doe", "password": "securePassword123", "type": "vendor", "vendorId": "507f1f77bcf86cd799439011", "approved": true } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the token is neither merchant- nor vendor-scoped, or a merchant token lacks the `admin:users` permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - Email already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users/{userId}": { "get": { "tags": [ "Users" ], "summary": "Get a single user", "description": "Retrieve a user by ObjectId. **Merchant scope only**.", "operationId": "getUser", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "User ObjectId", "example": "507f1f77bcf86cd799439012" } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required. There is no vendor-scoped variant of this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Users" ], "summary": "Update a user", "description": "Update an existing user.\n\nA **merchant** token may update any user on the shop. A **vendor**\ntoken may update only its own vendor's users.\n", "operationId": "updateUser", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "User ObjectId", "example": "507f1f77bcf86cd799439012" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRequest" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the token is neither merchant- nor vendor-scoped, or a merchant token lacks the `admin:users` permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - Email already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Users" ], "summary": "Delete a user", "description": "Delete a user account.\n\nA **merchant** token may delete any user on the shop. A **vendor**\ntoken may delete only its own vendor's users.\n", "operationId": "deleteUser", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "User ObjectId", "example": "507f1f77bcf86cd799439012" } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the token is neither merchant- nor vendor-scoped, or a merchant token lacks the `admin:users` permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/vendors": { "get": { "tags": [ "Vendors" ], "summary": "List vendors with pagination", "description": "Retrieve a paginated list of vendors. **Merchant scope only** - vendor tokens cannot access this endpoint.\n", "operationId": "listVendors", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search in vendor name and alias" }, { "in": "query", "name": "isHidden", "schema": { "type": "boolean" }, "description": "Filter by hidden status" }, { "in": "query", "name": "commissionType", "schema": { "type": "string", "enum": [ "percentage", "flat" ] }, "description": "Filter by commission type" }, { "in": "query", "name": "first", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return (forward pagination)" }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor for forward pagination" }, { "in": "query", "name": "last", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return (backward pagination)" }, { "in": "query", "name": "before", "schema": { "type": "string" }, "description": "Cursor for backward pagination" } ], "responses": { "200": { "description": "List of vendors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Vendors" ], "summary": "Create a new vendor", "description": "Create a new vendor in the shop. **Merchant scope only**.", "operationId": "createVendor", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRequest" }, "example": { "name": "Acme Corporation", "alias": "acme", "email": "vendor@acme.com", "commissionType": "percentage", "commissionRate": 15 } } } }, "responses": { "201": { "description": "Vendor created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Vendor" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - Vendor with this name or alias already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/vendors/{vendorId}": { "get": { "tags": [ "Vendors" ], "summary": "Get a single vendor", "description": "Retrieve a vendor by ObjectId. **Merchant scope only**.", "operationId": "getVendor", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" }, { "in": "query", "name": "includeUsers", "schema": { "type": "boolean" }, "description": "Include associated users in response" } ], "responses": { "200": { "description": "Vendor details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Vendor" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Vendors" ], "summary": "Update a vendor", "description": "Update an existing vendor. **Merchant scope only**.", "operationId": "updateVendor", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRequest" } } } }, "responses": { "200": { "description": "Vendor updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Vendor" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - Vendor name or alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Vendors" ], "summary": "Delete a vendor (soft delete)", "description": "Soft delete a vendor by setting isHidden=true. The vendor data is preserved but hidden from lists.\n**Merchant scope only**.\n", "operationId": "deleteVendor", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Vendor deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/vendors/{vendorId}/profile": { "get": { "tags": [ "Vendors" ], "summary": "Get vendor profile", "description": "Get vendor profile fields (company name, contact info, etc.). **Merchant scope only**.", "operationId": "getVendorProfile", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Vendor profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VendorProfile" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Vendors" ], "summary": "Update vendor profile", "description": "Update vendor profile fields. **Merchant scope only**.", "operationId": "updateVendorProfile", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorProfile" } } } }, "responses": { "200": { "description": "Vendor profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VendorProfile" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/vendors/{vendorId}/address": { "get": { "tags": [ "Vendors" ], "summary": "Get vendor address", "description": "Get vendor address fields. **Merchant scope only**.", "operationId": "getVendorAddress", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Vendor address", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VendorAddress" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found or no address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Vendors" ], "summary": "Update vendor address", "description": "Update vendor address fields. **Merchant scope only**.", "operationId": "updateVendorAddress", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "vendorId", "required": true, "schema": { "type": "string" }, "description": "Vendor ObjectId", "example": "507f1f77bcf86cd799439011" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorAddress" } } } }, "responses": { "200": { "description": "Vendor address updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/VendorAddress" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Merchant scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vendor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }