{"openapi":"3.1.0","info":{"title":"GET /api/v1/inventory/products/variants","version":"1.0.0","description":"List product variants"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/inventory/products/variants":{"get":{"tags":["inventory:products"],"summary":"List product variants","description":"Retrieve all variants with optional filtering by product.","operationId":"list_variants_api_v1_inventory_products_variants_get","parameters":[{"name":"product_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by parent product ID","title":"Product Id"},"description":"Filter by parent product ID"},{"name":"archived","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by archived status","title":"Archived"},"description":"Filter by archived status"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"Cursor"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Pagination limit","title":"Limit"},"description":"Pagination limit"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Pagination direction: 'next' or 'prev'","default":"next","title":"Direction"},"description":"Pagination direction: 'next' or 'prev'"},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to include total count (expensive - avoid if possible)","default":false,"title":"Include Total Count"},"description":"Whether to include total count (expensive - avoid if possible)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.","title":"Sort By"},"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None."},{"name":"descending","in":"query","required":false,"schema":{"type":"boolean","description":"Sort direction: true for descending (newest/largest first), false for ascending","default":true,"title":"Descending"},"description":"Sort direction: true for descending (newest/largest first), false for ascending"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantsListResponse"}}}},"404":{"description":"Business not found"},"422":{"description":"Invalid query parameters"}}}}},"components":{"schemas":{"InventorySummary":{"properties":{"on_hand":{"type":"number","minimum":0.0,"title":"On Hand","description":"Total physical inventory quantity in your possession.","default":0},"available":{"type":"number","minimum":0.0,"title":"Available","description":"Quantity available for allocation.","default":0},"in_transit":{"type":"number","minimum":0.0,"title":"In Transit","description":"Quantity currently being shipped to your location.","default":0},"ordered":{"type":"number","minimum":0.0,"title":"Ordered","description":"Quantity ordered from suppliers but not yet shipped.","default":0}},"type":"object","title":"InventorySummary","description":"Summary of inventory quantities for a product variant.\n\nTracks different inventory states to support proper stock management\nand prevent overselling.","example":{"available":100,"in_transit":25,"on_hand":100,"ordered":50}},"VariantResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Variant UUID."},"product_id":{"type":"string","title":"Product Id","description":"Parent product UUID."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp."},"name":{"type":"string","title":"Name","description":"Variant name."},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku","description":"Stock Keeping Unit."},"manufacturer_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manufacturer Sku","description":"Manufacturer's SKU."},"archived":{"type":"boolean","title":"Archived","description":"Whether variant is archived.","default":false},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Unit price in dollars (legacy field, prefer unit_price)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Unit cost in dollars (legacy field, prefer unit_cost)."},"inventory_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Inventory Quantity","description":"Current inventory quantity (legacy, prefer inventory.on_hand)."},"shopify_variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shopify Variant Id","description":"Shopify variant ID if synced from Shopify."},"stripe_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id","description":"Stripe price ID if synced to Stripe."},"stripe_product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Product Id","description":"Stripe product ID if synced to Stripe."},"unit_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unit Price","description":"Sale price in cents."},"unit_cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unit Cost","description":"Cost price in cents."},"unit_cost_precise":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unit Cost Precise","description":"Precise unit cost in dollars with sub-cent precision."},"uom":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uom","description":"Unit of measure: EA, LB, G, KG, OZ, etc."},"default_vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Vendor Id","description":"Preferred vendor UUID."},"inventory":{"anyOf":[{"$ref":"#/components/schemas/InventorySummary"},{"type":"null"}],"description":"Detailed inventory breakdown."},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"Parent product name (resolved)."},"margin_cents":{"type":"integer","title":"Margin Cents","description":"Profit margin in cents (unit_price - unit_cost).","readOnly":true},"margin_percentage":{"type":"number","title":"Margin Percentage","description":"Profit margin as percentage of sale price.","readOnly":true}},"additionalProperties":true,"type":"object","required":["id","product_id","business_id","created_at","updated_at","name","margin_cents","margin_percentage"],"title":"VariantResponse","description":"Response schema for a product variant.\n\nContains pricing, inventory, and margin information.\nIncludes computed fields for profit margin calculations.","example":{"archived":false,"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2024-01-10T10:30:00Z","id":"019ab37c-var1-7000-8000-000000000001","inventory":{"available":50,"in_transit":0,"on_hand":50,"ordered":0},"manufacturer_sku":"MFR-12345","margin_cents":1799,"margin_percentage":60.02,"name":"Large - Blue","product_id":"019ab37c-prod-7000-8000-000000000001","product_name":"Premium Widget","sku":"WIDGET-PRO-LG-BLU","unit_cost":1200,"unit_price":2999,"updated_at":"2024-01-15T14:00:00Z"}},"VariantsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/VariantResponse"},"type":"array","title":"Items","description":"List of items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total number of items (null when not calculated for performance)"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Pagination limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for next page"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor","description":"Cursor for previous page"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous items"}},"type":"object","required":["items","has_next","has_prev"],"title":"VariantsListResponse","description":"Paginated list of variants with cursor-based navigation."}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}