{"openapi":"3.0.0","info":{"title":"Shopiators Public API","version":"1.0.0","description":"The Shopiators Public API is the official API for integrating applications, migration tools, technology partners and third-party services with Shopiators ecommerce stores.\n\nThe API provides programmatic access to supported Shopiators store resources and can be used for ecommerce integrations, migration workflows, catalog synchronization and supported data import/export workflows."},"servers":[{"url":"https://api.shopiators.com/api/v1","description":"Production server"}],"tags":[{"name":"Auth","description":"Authentication endpoints"},{"name":"Products","description":"Product management"},{"name":"Collections","description":"Collection management"},{"name":"Attribute Sets","description":"Attribute Set management"},{"name":"Attributes","description":"Attribute management"},{"name":"Customers","description":"Customer (Store User) management"},{"name":"Addresses","description":"Customer Address management"},{"name":"Orders","description":"Order management"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Enter your API key here (e.g. sk_live_...)"}},"schemas":{"AttributeSet":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4abc"},"name":{"type":"string","example":"Clothing Attributes"},"status":{"type":"string","enum":["active","inactive"],"example":"active"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AttributeValue":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4def"},"attribute":{"type":"string","description":"ObjectId reference to parent Attribute","example":"64f1e2b3c9e77b001f8e4aaa"},"name":{"type":"string","example":"Red"},"value":{"type":"string","example":"Red"},"hex":{"type":"string","description":"Optional hex code for color swatches","example":"#FF0000"},"status":{"type":"string","enum":["active","inactive"],"example":"active"},"createdAt":{"type":"string","format":"date-time"}}},"Attribute":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4aaa"},"name":{"type":"string","example":"Color"},"attributeset":{"type":"string","description":"ObjectId reference to an AttributeSet","example":"64f1e2b3c9e77b001f8e4abc"},"values":{"type":"array","description":"Array of AttributeValue ObjectIds","items":{"type":"string"},"example":["64f1e2b3c9e77b001f8e4def"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Variant":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4bbb"},"productId":{"type":"string","description":"ObjectId reference to parent Product","example":"64f1e2b3c9e77b001f8e4ccc"},"attributes":{"type":"object","description":"Key-value map of attribute name to value (e.g. { \"Color\": \"Red\", \"Size\": \"M\" })","additionalProperties":{"type":"string"},"example":{"Color":"Red","Size":"M"}},"price":{"type":"number","example":15},"salePrice":{"type":"number","example":12},"stock":{"type":"number","example":100},"sku":{"type":"string","example":"TSHIRT-RED-M"},"createdAt":{"type":"string","format":"date-time"}}},"Product":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4ccc"},"title":{"type":"string","example":"Premium Cotton T-Shirt"},"handle":{"type":"string","description":"URL-friendly slug (auto-generated if not provided)","example":"premium-cotton-t-shirt"},"description":{"type":"string","example":"A comfortable 100% cotton t-shirt."},"status":{"type":"string","enum":["active","disabled"],"example":"active"},"badge":{"type":"string","example":"New"},"price":{"type":"number","example":15},"salePrice":{"type":"number","description":"Strike-through/original price (mapped from comparePrice on input)","example":20},"comparePrice":{"type":"number","description":"Compare at price (must be >= price)","example":20},"totalStock":{"type":"number","example":200},"image":{"type":"array","items":{"type":"string"},"example":["https://images.example.com/shirt.jpg"]},"sizeChart":{"type":"string","description":"URL or base64 data URI of size chart","example":"https://images.example.com/sizechart.jpg"},"selectedCollection":{"type":"array","description":"Array of Collection ObjectIds this product belongs to","items":{"type":"string"},"example":["64f1e2b3c9e77b001f8e4ddd"]},"attributeSet":{"type":"string","description":"ObjectId reference to an AttributeSet","example":"64f1e2b3c9e77b001f8e4abc"},"options":{"type":"array","description":"Product variant options (e.g. Size, Color)","items":{"type":"object","properties":{"name":{"type":"string","example":"Size"},"values":{"type":"array","items":{"type":"string"},"example":["Small","Medium","Large"]}}}},"variants":{"type":"array","description":"Array of populated Variant objects","items":{"$ref":"#/components/schemas/Variant"}},"metaTitle":{"type":"string","example":"Buy Premium Cotton T-Shirt Online"},"metaDescription":{"type":"string","example":"100% Cotton T-Shirt in multiple sizes."},"metaKeywords":{"type":"string","example":"t-shirt, cotton, clothing"},"returnConfig":{"type":"object","properties":{"useGlobalConfig":{"type":"boolean","example":true},"returnable":{"type":"boolean"},"exchangeable":{"type":"boolean"},"customReturnWindow":{"type":"number","description":"Days; overrides store setting when useGlobalConfig is false"}}},"averageRating":{"type":"number","example":4.5},"totalReviews":{"type":"number","example":120},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Collection":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4ddd"},"title":{"type":"string","example":"Summer Sale"},"handle":{"type":"string","description":"URL-friendly slug","example":"summer-sale"},"description":{"type":"string","example":"Best deals of the summer season."},"image":{"type":"string","example":"https://images.example.com/summer-sale.jpg"},"collectionType":{"type":"string","enum":["manual","smart"],"example":"manual"},"selectedProducts":{"type":"array","description":"Array of Product ObjectIds (for manual collections)","items":{"type":"string"},"example":["64f1e2b3c9e77b001f8e4ccc"]},"parentCollection":{"type":"string","description":"ObjectId of parent collection","example":"64f1e2b3c9e77b001f8e4eee"},"childCollection":{"type":"array","description":"Array of child Collection ObjectIds","items":{"type":"string"}},"matchType":{"type":"string","enum":["all condition","any condition"],"description":"Used for smart collections","example":"all condition"},"conditions":{"type":"array","description":"Smart collection filter rules","items":{"type":"object","properties":{"field":{"type":"string","example":"title"},"operator":{"type":"string","example":"contains"},"value":{"type":"string","example":"shirt"}}}},"metaTitle":{"type":"string","example":"Summer Sale Collection"},"metaDescription":{"type":"string","example":"Shop our best summer deals."},"metaKeywords":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":25},"total":{"type":"integer","example":100},"totalPages":{"type":"integer","example":4}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"price should be less than compare at price"},"details":{"type":"array","items":{"type":"object"}}}}}},"Customer":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4ccc"},"userName":{"type":"string","example":"johndoe123"},"email":{"type":"string","example":"john@example.com"},"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"businessName":{"type":"string","example":"Doe Industries"},"phoneNumber":{"type":"string","example":"+1234567890"},"role":{"type":"string","example":"user"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AddressPayload":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4cdd"},"name":{"type":"string","example":"Home Address"},"email":{"type":"string","example":"john@example.com"},"house":{"type":"string","example":"Apt 4B"},"street":{"type":"string","example":"123 Main St"},"landmark":{"type":"string","example":"Near Central Park"},"city":{"type":"string","example":"New York"},"stateName":{"type":"string","example":"New York"},"countryName":{"type":"string","example":"United States"},"pincode":{"type":"string","example":"10001"},"phone":{"type":"string","example":"+1234567890"},"addressType":{"type":"string","enum":["Home","Work","Other"],"example":"Home"},"isDefault":{"type":"boolean","example":true}}},"Address":{"type":"object","properties":{"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"address1":{"type":"string","example":"123 Main St"},"address2":{"type":"string","example":"Apt 4B"},"city":{"type":"string","example":"New York"},"state":{"type":"string","example":"NY"},"zip":{"type":"string","example":"10001"},"country":{"type":"string","example":"USA"},"phone":{"type":"string","example":"+1234567890"}}},"Order":{"type":"object","properties":{"id":{"type":"string","example":"64f1e2b3c9e77b001f8e4ccc"},"customOrderId":{"type":"string","example":"ORD-1698765432-ABC"},"userId":{"type":"string"},"cartItems":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"title":{"type":"string","example":"Premium T-Shirt"},"price":{"type":"number","example":25},"quantity":{"type":"number","example":2},"sku":{"type":"string","example":"TSHIRT-01"}}}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/Address"},"contactEmail":{"type":"string","example":"customer@example.com"},"orderStatus":{"type":"string","example":"pending"},"paymentMethod":{"type":"string","example":"credit_card"},"paymentStatus":{"type":"string","example":"paid"},"subTotal":{"type":"number","example":50},"shippingCharge":{"type":"number","example":5},"taxAmount":{"type":"number","example":5.5},"totalAmount":{"type":"number","example":60.5},"currency":{"type":"string","example":"USD"},"trackingInfo":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string"},"shippingCarrier":{"type":"string"},"trackingUrl":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"handle","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","disabled"]}},{"in":"query","name":"sort","schema":{"type":"string","enum":["createdAt","-createdAt","price","-price","title","-title"]}}],"responses":{"200":{"description":"A list of products","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create product","description":"Creates a new product in the store.\n\n**Notes**:\n- `handle` is auto-generated from title if not provided (guaranteed unique).\n- `comparePrice` must be **≥** `price`, otherwise a validation error is returned.\n- `images` accepts URLs or base64 data URIs — they will be uploaded to FTP automatically.\n- `selectedCollections` must be valid ObjectIds belonging to the same store.\n- Providing `options` (e.g. Size, Color) will auto-generate variants and attribute combinations.\n","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Premium Cotton T-Shirt"},"handle":{"type":"string","description":"URL slug. Must be unique per store. Auto-generated if omitted.","example":"premium-cotton-t-shirt"},"description":{"type":"string","example":"A comfortable 100% cotton t-shirt."},"status":{"type":"string","enum":["active","disabled"],"example":"active"},"price":{"type":"number","example":15},"comparePrice":{"type":"number","description":"Compare at / original price. Must be >= price.","example":20},"totalStock":{"type":"number","example":100},"images":{"type":"array","description":"Array of image URLs or base64 data URIs","items":{"type":"string"},"example":["https://example.com/image1.jpg"]},"sizeChart":{"type":"string","description":"URL or base64 data URI of the size chart","example":"https://example.com/sizechart.jpg"},"selectedCollections":{"type":"array","description":"Array of Collection ObjectIds","items":{"type":"string"},"example":[]},"metaTitle":{"type":"string","example":"Buy Premium Cotton T-Shirt Online"},"metaDescription":{"type":"string","example":"100% Cotton T-Shirt in multiple sizes."},"options":{"type":"array","description":"Product variant options. Each option generates variants automatically.","items":{"type":"object","properties":{"name":{"type":"string","example":"Size"},"values":{"type":"array","items":{"type":"string"},"example":["Small","Medium","Large"]}}}}}}}}},"responses":{"201":{"description":"Created product","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"summary":"Get a product by ID","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"64f1e2b3c9e77b001f8e4ccc"}],"responses":{"200":{"description":"Product details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update product","description":"All fields are optional. `comparePrice` must remain >= `price` if both are provided.\nProviding a `handle` that already belongs to another product will return a 400 error.\n","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"handle":{"type":"string","description":"Must be unique per store"},"description":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"price":{"type":"number"},"comparePrice":{"type":"number","description":"Must be >= price"},"totalStock":{"type":"number"},"images":{"type":"array","description":"Existing URLs (kept as-is) or base64 data URIs (re-uploaded)","items":{"type":"string"}},"sizeChart":{"type":"string"},"selectedCollections":{"type":"array","items":{"type":"string"}},"metaTitle":{"type":"string"},"metaDescription":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated product","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete product","description":"Deletes a product along with its variants and attribute combinations (cascade delete).","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","description":"Filter by orderStatus"}},{"in":"query","name":"paymentStatus","schema":{"type":"string","description":"Filter by paymentStatus"}},{"in":"query","name":"sort","schema":{"type":"string","enum":["createdAt","-createdAt","totalAmount","-totalAmount"],"default":"-createdAt"}}],"responses":{"200":{"description":"A list of orders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create an order","description":"Creates a new order in the store. Useful for migration workflows or custom checkouts.\n\n**Notes**:\n- `customOrderId` will be auto-generated (e.g. `ORD-...`) if not provided.\n- You must provide at least one item in `cartItems`.\n","tags":["Orders"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cartItems","subTotal","totalAmount"],"properties":{"customOrderId":{"type":"string","description":"Unique identifier for the order. Auto-generated if omitted.","example":"ORD-12345"},"cartItems":{"type":"array","items":{"type":"object","required":["productId","title","price","quantity"],"properties":{"productId":{"type":"string"},"title":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"number"},"sku":{"type":"string"}}}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/Address"},"contactEmail":{"type":"string","example":"customer@example.com"},"orderStatus":{"type":"string","example":"pending"},"paymentMethod":{"type":"string","example":"credit_card"},"paymentStatus":{"type":"string","example":"paid"},"subTotal":{"type":"number","example":50},"shippingCharge":{"type":"number","example":5},"taxAmount":{"type":"number","example":5.5},"totalAmount":{"type":"number","example":60.5},"currency":{"type":"string","default":"USD"}}}}}},"responses":{"201":{"description":"Created order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"summary":"Get an order by ID","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"64f1e2b3c9e77b001f8e4ccc"}],"responses":{"200":{"description":"Order details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update an order","description":"Update the order status, payment status, tracking info, or handle refunds/returns.\nFields will be deeply merged where applicable (e.g., updating `refund.status` leaves the rest of the refund object intact).\n","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderStatus":{"type":"string","example":"fulfilled"},"paymentStatus":{"type":"string","example":"paid"},"trackingInfo":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string"},"shippingCarrier":{"type":"string"},"trackingUrl":{"type":"string"}}}},"refund":{"type":"object","properties":{"status":{"type":"string","example":"Approved"},"adminRemark":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Updated order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of customers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create a customer","description":"Create a new customer (user role) in the store. \nIf an `address` block is provided, an Address record will be automatically created and linked to the new customer.\n","tags":["Customers"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userName","password"],"properties":{"userName":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"phoneNumber":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressPayload"}}}}}},"responses":{"201":{"description":"Created customer","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Customer"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"get":{"summary":"Get a customer by ID","tags":["Customers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Customer details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Customer"}}}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated customer","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Customer"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{customerId}/addresses":{"get":{"summary":"List addresses for a customer","tags":["Customers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"customerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of customer addresses","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AddressPayload"}}}}}}}}},"post":{"summary":"Add an address to a customer","tags":["Customers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"customerId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPayload"}}}},"responses":{"201":{"description":"Created address","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AddressPayload"}}}}}}}}},"/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"sort","schema":{"type":"string","enum":["createdAt","-createdAt","title","-title"]}}],"responses":{"200":{"description":"A list of collections","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create collection","tags":["Collections"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Summer Sale"},"handle":{"type":"string","example":"summer-sale"},"description":{"type":"string","example":"Best deals of the summer."},"image":{"type":"string","example":"https://images.example.com/banner.jpg"},"collectionType":{"type":"string","enum":["manual","smart"],"example":"manual"},"selectedProducts":{"type":"array","description":"Array of Product ObjectIds (for manual collections)","items":{"type":"string"},"example":[]},"parentCollection":{"type":"string","description":"ObjectId of parent collection"},"matchType":{"type":"string","enum":["all condition","any condition"],"description":"For smart collections"},"conditions":{"type":"array","description":"Smart collection filter rules","items":{"type":"object","properties":{"field":{"type":"string","example":"title"},"operator":{"type":"string","example":"contains"},"value":{"type":"string","example":"shirt"}}}},"metaTitle":{"type":"string"},"metaDescription":{"type":"string"},"metaKeywords":{"type":"string"}}}}}},"responses":{"201":{"description":"Created collection","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Collection"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections/{id}":{"get":{"summary":"Get a collection by ID","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"64f1e2b3c9e77b001f8e4ddd"}],"responses":{"200":{"description":"Collection details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Collection"}}}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update collection","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"handle":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"collectionType":{"type":"string","enum":["manual","smart"]},"selectedProducts":{"type":"array","items":{"type":"string"}},"parentCollection":{"type":"string"},"matchType":{"type":"string","enum":["all condition","any condition"]},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"}}}},"metaTitle":{"type":"string"},"metaDescription":{"type":"string"},"metaKeywords":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated collection","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Collection"}}}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete collection","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth":{"post":{"summary":"Authenticate merchant","description":"Authenticate a store admin using storeSlug, email, and password to receive a JWT access token.","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["storeSlug","email","password"],"properties":{"storeSlug":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Successfully authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"accessToken":{"type":"string"},"tokenType":{"type":"string"},"expiresIn":{"type":"number"}}}}}}}},"401":{"description":"Invalid credentials"},"429":{"description":"Too many requests"}}}},"/attributes":{"get":{"summary":"List attributes","tags":["Attributes"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"sort","schema":{"type":"string","enum":["createdAt","-createdAt","name","-name"]}}],"responses":{"200":{"description":"A list of attributes","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Attribute"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create attribute","description":"Creates a new attribute. The `values` array accepts plain strings (e.g. \"Red\", \"Blue\").\nIf an AttributeValue with that name already exists for this attribute, its ID will be reused.\nOtherwise a new AttributeValue will be created automatically.\n","tags":["Attributes"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Color"},"attributeset":{"type":"string","description":"ObjectId of an existing AttributeSet","example":"64f1e2b3c9e77b001f8e4abc"},"values":{"type":"array","description":"Array of value names (strings). IDs will be resolved/created automatically.","items":{"type":"string"},"example":["Red","Blue","Green"]}}}}}},"responses":{"201":{"description":"Created attribute","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Attribute"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attributes/{id}":{"get":{"summary":"Get an attribute by ID","tags":["Attributes"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"64f1e2b3c9e77b001f8e4aaa"}],"responses":{"200":{"description":"Attribute details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Attribute"}}}}}},"404":{"description":"Attribute not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update attribute","description":"Updates an attribute. The `values` array accepts plain strings — same upsert logic as create applies.\n","tags":["Attributes"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Size"},"attributeset":{"type":"string","example":"64f1e2b3c9e77b001f8e4abc"},"values":{"type":"array","items":{"type":"string"},"example":["Small","Medium","Large"]}}}}}},"responses":{"200":{"description":"Updated attribute","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Attribute"}}}}}},"404":{"description":"Attribute not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete attribute","tags":["Attributes"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attribute deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"404":{"description":"Attribute not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attribute-sets":{"get":{"summary":"List attribute sets","tags":["Attribute Sets"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":25}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","inactive"]}},{"in":"query","name":"sort","schema":{"type":"string","enum":["createdAt","-createdAt","name","-name"]}}],"responses":{"200":{"description":"A list of attribute sets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AttributeSet"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Create attribute set","tags":["Attribute Sets"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Clothing Attributes"},"status":{"type":"string","enum":["active","inactive"],"example":"active"}}}}}},"responses":{"201":{"description":"Created attribute set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AttributeSet"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attribute-sets/{id}":{"get":{"summary":"Get an attribute set by ID","tags":["Attribute Sets"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"64f1e2b3c9e77b001f8e4abc"}],"responses":{"200":{"description":"Attribute set details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AttributeSet"}}}}}},"404":{"description":"Attribute set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update attribute set","tags":["Attribute Sets"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Updated Attribute Set Name"},"status":{"type":"string","enum":["active","inactive"]}}}}}},"responses":{"200":{"description":"Updated attribute set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AttributeSet"}}}}}},"404":{"description":"Attribute set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete attribute set","tags":["Attribute Sets"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attribute set deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"404":{"description":"Attribute set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/addresses/{id}":{"get":{"summary":"Get an address by ID","tags":["Addresses"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Address details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AddressPayload"}}}}}},"404":{"description":"Address not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update an address","tags":["Addresses"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"isDefault":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated address","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AddressPayload"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Address not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an address","tags":["Addresses"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","nullable":true}}}}}},"404":{"description":"Address not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"debug_id":"req_8422cd82ff864adcb3ccdcdd4a9a5e7d"}