{"authentication":{"type":"Bearer","format":"Bearer YOUR_API_TOKEN","header":"Authorization","token_rotation":"Zero-downtime rotation supported with 2 active tokens per environment"},"error_handling":{"format":"Consistent JSON error responses","codes":{"400":"Bad Request - Validation error","401":"Unauthorized - Invalid or missing token","404":"Not Found - Resource doesn't exist","409":"Conflict - Resource state conflict","422":"Unprocessable Entity - Business logic error","429":"Too Many Requests - Rate limited","503":"Service Unavailable - Temporary issue"}},"base_url":"https://api.catalogapi.com/api/v2","documentation":"https://api.catalogapi.com/api/docs","contact":{"documentation":"https://api.catalogapi.com/api/docs","faq":"https://api.catalogapi.com/faq","support":"Use contact form at https://api.catalogapi.com/faq"},"ai_agent_notes":["OpenAPI 3.1 specification available for automatic code generation","All endpoints return consistent JSON responses","Use any socket for sandbox testing","Implement exponential backoff for rate limits","Cache catalog data with 12-hour TTL for performance","Use context headers X-Trace-ID and X-Correlation-ID for better support","New accounts require the developer to generate a sandbox key before you begin"],"ai_integration_guide":"https://api.catalogapi.com/developers/ai-agents","api_version":"2.0","capabilities":["Product catalog with 2M+ items across 150 countries","Cart management with session persistence","Order placement and fulfillment tracking","Real-time inventory management","Multi-currency and multi-language support","Webhook notifications for order status","Supplier API integration available"],"common_workflows":[{"name":"Product Search & Browse","description":"Find and explore products in the catalog","example_params":{"filters":"category_id=123&min_price=10&max_price=100&is_primary=true","search":"search=tacos&page=1&per_page=20"},"steps":["GET /sockets - List available catalogs/sockets for your account","GET /sockets/{socket_id}/categories - Browse category hierarchy","GET /sockets/{socket_id}/categories/tag/{tag_id} - Filter categories by tag","GET /sockets/{socket_id}/items?search={query} - Search products by keyword","GET /sockets/{socket_id}/items?category_id={id} - List products in category","GET /sockets/{socket_id}/items/{item_id} - Get full product details with images"]},{"name":"Shopping Cart Management","description":"Build and manage shopping carts with session persistence","steps":["POST /sockets/{socket_id}/cart/{external_user_id}/items - Add items to cart","GET /sockets/{socket_id}/cart/{external_user_id} - View current cart","PUT /sockets/{socket_id}/cart/{external_user_id}/line_items/{line_item_id} - Update line item metadata","DELETE /sockets/{socket_id}/cart/{external_user_id}/line_items/{line_item_id} - Remove item","PUT /sockets/{socket_id}/cart/{external_user_id}/address - Set shipping address","PUT /sockets/{socket_id}/cart/{external_user_id}/metadata - Add custom metadata"],"notes":["external_user_id is your unique identifier for the user","Cart line items have no quantity, you add them individually so each can have its own distinct ID for later fulfillment messages","Individual line item metadata can be used to tag line items against other systems like Stripe or TaxJar","Carts are locked during checkout to prevent concurrent modifications","You can simulate quantity in your application by combining line items by their catalog_item_id"]},{"name":"Checkout & Order Placement","description":"Convert cart to order with payment tracking","steps":["POST /sockets/{socket_id}/cart/{external_user_id}/validate - Validate cart before order","POST /sockets/{socket_id}/cart/{external_user_id}/order - Place the order"],"example_order":{"external_order_id":"ORD-2024-001","line_item_payments":[{"line_item_id":"a53fbc34-cd37-4227-8aa7-c4ced9ddc683","points_paid":5000,"price_paid":"100.00","shipping_paid":"10.00","tax_paid":"8.25"}],"cart_version":"abc-123"},"payment_fields":{"points_paid":"Loyalty points used by end user (informational)","price_paid":"Amount you pay to CatalogAPI (wholesale cost)","shipping_paid":"Shipping fee charged to end user (pass-through)","tax_paid":"Sales tax collected from end user (pass-through)"}},{"name":"Order Tracking","description":"Monitor order status and shipments","steps":["GET /orders - List all orders with filters","GET /orders/{external_order_id} - Get detailed order information"],"notes":["Each line item has its own status","Webhooks can be used to notify your system when order item statuses change"],"order_item_states":["new","exported","fulfilled","backordered","cancelled"]}],"data_structures":{"order":{"id":"CatalogAPI order ID","external_order_id":"Your order identifier","fulfillments":"Shipment tracking info","line_items":"Ordered items"},"catalog_item":{"id":"Unique identifier","name":"Product name","description":"Detailed description","metadata":"Additional product attributes","currency":"ISO 4217 currency code","tags":"Array of tag names","categories":"Array of category IDs","images":"Array of image URLs","price":"Current price in specified currency","shipping_estimate":"Estimated shipping cost","in_stock":"Boolean availability"},"cart":{"id":"Cart identifier","total":"Cart total in currency","version":"Optimistic locking token","currency":"Cart currency","external_user_id":"Your user identifier","line_items":"Array of cart items"}},"environments":{"sandbox":{"description":"Test environment that uses the same catalog data as live, but orders do not fulfill with real data","base_url":"https://api.catalogapi.com/sandbox/api/v2"},"production":{"description":"Live environment for production use","base_url":"https://api.catalogapi.com/api/v2"}},"implementation_tips":{"authentication":["Generate tokens in dashboard at https://api.catalogapi.com","Use Bearer authentication: 'Authorization: Bearer YOUR_TOKEN'","Sandbox tokens only work on /sandbox/api/v2/* endpoints","Production tokens only work on /api/v2/* endpoints","Support zero-downtime rotation with 2 active tokens per environment"],"testing":["Use any socket_id for sandbox testing","Verify webhook endpoint before going live","Test token rotation process in sandbox first","Validate handling of out-of-stock scenarios"],"best_practices":["Always validate cart before placing order","Store external_order_id for order tracking","Handle 409 conflicts gracefully (cart already locked, etc)","Use descriptive external_user_id for easier debugging","Test in sandbox before production deployment","Implement proper error handling for all status codes","Never expose API tokens to client-side code"],"performance":["Cache catalog data (categories, items) with 12-hour TTL","Use pagination for large result sets (limit/offset parameters)","Implement exponential backoff for rate limit (429) responses","Batch cart operations when possible to reduce API calls","Use webhook notifications instead of polling for order updates"]},"key_concepts":{"sockets":"Containers for catalog configurations. Each socket represents a catalog with specific products, pricing, and settings","tags":"Product categorization labels (e.g., 'On Sale', 'New', 'Featured'). Use for filtering and discovery","line_item_id":"Unique identifier for items in cart. Generated by API when items added. Use for updates/deletions","external_user_id":"Your unique identifier for users. Can be any string (email, UUID, username). Used to maintain cart sessions","catalog_item_id":"Global product identifier. Same item may have different prices/availability across sockets","cart_version":"Optimistic locking token returned with cart. Include in order placement to prevent race conditions"},"openapi_spec":"https://api.catalogapi.com/api/v2/openapi-clean","rate_limits":{"headers":["X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset"],"hourly":1000,"per_minute":100},"sandbox_url":"https://api.catalogapi.com/sandbox/api/v2"}