# Products

Product management endpoints

## Create Product

> Creates a new product in the system

```json
{"openapi":"3.1.1","info":{"title":"Brand Developer API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product management endpoints"}],"servers":[{"url":"https://api.maisonsafqa.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-MaisonSafqa-Api-Key","description":"API key authentication. Pass your API key directly in the X-MaisonSafqa-Api-Key header (e.g., 'ms_test_your_api_key_here' for test environment or 'ms_live_your_api_key_here' for production environment)"}},"schemas":{"ProductResponse":{"type":"object","properties":{"error":{"type":"null"},"product":{"$ref":"#/components/schemas/Product"},"message":{"type":"string"}}},"Product":{"type":"object","properties":{"id":{"type":"string","description":"Product identifier - external_id (Shopify ID) for synced products, product_id for unsynced products"},"title":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"handle":{"type":"string","description":"URL slug"},"status":{"type":"string","description":"Product status"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariantResponse"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageResponse"}},"product_type":{"type":"string","description":"Product category"},"vendor":{"type":"string","description":"Brand/vendor name"},"tags":{"type":"string","description":"Comma-separated tags"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"synced":{"type":"boolean","description":"Whether product is synced to Shopify"},"last_synced_at":{"type":"string","format":"date-time","description":"Last sync timestamp"}}},"ProductVariantResponse":{"type":"object","properties":{"id":{"type":"string","description":"Variant ID"},"title":{"type":"string","description":"Variant name"},"sku":{"type":"string","description":"Variant SKU"},"price":{"type":"number","description":"Price in SAR (converted from brand currency)"},"compare_at_price":{"type":"number","description":"Compare at price in SAR"},"inventory_quantity":{"type":"integer","description":"Current stock quantity"},"weight":{"type":"number","description":"Variant weight"},"weight_unit":{"type":"string","description":"Weight unit"},"requires_shipping":{"type":"boolean","description":"Requires shipping"},"taxable":{"type":"boolean","description":"Is taxable"},"barcode":{"type":"string","description":"Product barcode"},"option1":{"type":"string","description":"Option 1 value"},"option2":{"type":"string","description":"Option 2 value"},"option3":{"type":"string","description":"Option 3 value"}}},"ProductImageResponse":{"type":"object","properties":{"id":{"type":"string","description":"Image ID"},"src":{"type":"string","description":"Image URL"},"alt":{"type":"string","description":"Alt text"},"position":{"type":"integer","description":"Display order"}}},"ErrorResponse":{"type":"object","properties":{"error":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","description":"Field that caused the error"},"message":{"type":"string","description":"Human readable error message"}}},{"type":"string","description":"Error message"}]}}},"CreateProductRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255,"description":"Product name"},"body_html":{"type":"string","maxLength":65535,"description":"Product description (HTML allowed)"},"vendor":{"type":"string","maxLength":255,"description":"Brand/vendor name"},"product_type":{"type":"string","maxLength":255,"description":"Product category"},"tags":{"type":"string","maxLength":1000,"description":"Comma-separated tags"},"handle":{"type":"string","pattern":"^[a-z0-9-]+$","description":"URL slug (auto-generated if not provided)"},"template_suffix":{"type":"string","maxLength":255,"description":"Template suffix"},"published_scope":{"type":"string","description":"Published scope","default":"web"},"variants":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ProductVariant"},"description":"At least one variant required"},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImage"},"description":"Product images"}},"required":["title","variants"]},"ProductVariant":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255,"description":"Variant name"},"sku":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Z0-9_-]+$","description":"Unique SKU (alphanumeric, hyphens, underscores)"},"price":{"type":"number","minimum":0,"description":"Price in brand currency"},"compare_at_price":{"type":"number","minimum":0,"description":"Compare at price"},"inventory_quantity":{"type":"integer","minimum":0,"description":"Stock quantity"},"weight":{"type":"number","minimum":0,"description":"Weight in specified unit"},"weight_unit":{"type":"string","maxLength":50,"description":"Weight unit","default":"kg"},"barcode":{"type":"string","maxLength":255,"description":"Product barcode"},"requires_shipping":{"type":"boolean","description":"Requires shipping","default":true},"taxable":{"type":"boolean","description":"Is taxable","default":true}},"required":["title","sku","price","inventory_quantity"]},"ProductImage":{"type":"object","properties":{"src":{"type":"string","format":"uri","description":"Image URL (must be valid URL)"},"alt":{"type":"string","maxLength":500,"description":"Alt text for accessibility"},"position":{"type":"integer","minimum":1,"maximum":100,"description":"Display order"}},"required":["src"]}}},"paths":{"/products":{"post":{"tags":["Products"],"summary":"Create Product","description":"Creates a new product in the system","responses":{"201":{"description":"Product created successfully","headers":{"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when rate limit resets"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in current window"},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed per minute"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"Validation errors or duplicate SKUs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}},"required":true}}}}}
```

## Get Product

> Retrieves a specific product by ID. Use external\_id for synced products or product\_id for unsynced products.

```json
{"openapi":"3.1.1","info":{"title":"Brand Developer API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product management endpoints"}],"servers":[{"url":"https://api.maisonsafqa.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-MaisonSafqa-Api-Key","description":"API key authentication. Pass your API key directly in the X-MaisonSafqa-Api-Key header (e.g., 'ms_test_your_api_key_here' for test environment or 'ms_live_your_api_key_here' for production environment)"}},"schemas":{"ProductResponse":{"type":"object","properties":{"error":{"type":"null"},"product":{"$ref":"#/components/schemas/Product"},"message":{"type":"string"}}},"Product":{"type":"object","properties":{"id":{"type":"string","description":"Product identifier - external_id (Shopify ID) for synced products, product_id for unsynced products"},"title":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"handle":{"type":"string","description":"URL slug"},"status":{"type":"string","description":"Product status"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariantResponse"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageResponse"}},"product_type":{"type":"string","description":"Product category"},"vendor":{"type":"string","description":"Brand/vendor name"},"tags":{"type":"string","description":"Comma-separated tags"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"synced":{"type":"boolean","description":"Whether product is synced to Shopify"},"last_synced_at":{"type":"string","format":"date-time","description":"Last sync timestamp"}}},"ProductVariantResponse":{"type":"object","properties":{"id":{"type":"string","description":"Variant ID"},"title":{"type":"string","description":"Variant name"},"sku":{"type":"string","description":"Variant SKU"},"price":{"type":"number","description":"Price in SAR (converted from brand currency)"},"compare_at_price":{"type":"number","description":"Compare at price in SAR"},"inventory_quantity":{"type":"integer","description":"Current stock quantity"},"weight":{"type":"number","description":"Variant weight"},"weight_unit":{"type":"string","description":"Weight unit"},"requires_shipping":{"type":"boolean","description":"Requires shipping"},"taxable":{"type":"boolean","description":"Is taxable"},"barcode":{"type":"string","description":"Product barcode"},"option1":{"type":"string","description":"Option 1 value"},"option2":{"type":"string","description":"Option 2 value"},"option3":{"type":"string","description":"Option 3 value"}}},"ProductImageResponse":{"type":"object","properties":{"id":{"type":"string","description":"Image ID"},"src":{"type":"string","description":"Image URL"},"alt":{"type":"string","description":"Alt text"},"position":{"type":"integer","description":"Display order"}}},"ErrorResponse":{"type":"object","properties":{"error":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","description":"Field that caused the error"},"message":{"type":"string","description":"Human readable error message"}}},{"type":"string","description":"Error message"}]}}}}},"paths":{"/products/{id}":{"get":{"tags":["Products"],"summary":"Get Product","description":"Retrieves a specific product by ID. Use external_id for synced products or product_id for unsynced products.","parameters":[{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"Product identifier - external_id (Shopify ID) for synced products, or product_id for unsynced products"}],"responses":{"200":{"description":"Product retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update Product

> Updates an existing product. Use external\_id for synced products or product\_id for unsynced products.

```json
{"openapi":"3.1.1","info":{"title":"Brand Developer API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product management endpoints"}],"servers":[{"url":"https://api.maisonsafqa.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-MaisonSafqa-Api-Key","description":"API key authentication. Pass your API key directly in the X-MaisonSafqa-Api-Key header (e.g., 'ms_test_your_api_key_here' for test environment or 'ms_live_your_api_key_here' for production environment)"}},"schemas":{"ProductResponse":{"type":"object","properties":{"error":{"type":"null"},"product":{"$ref":"#/components/schemas/Product"},"message":{"type":"string"}}},"Product":{"type":"object","properties":{"id":{"type":"string","description":"Product identifier - external_id (Shopify ID) for synced products, product_id for unsynced products"},"title":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"handle":{"type":"string","description":"URL slug"},"status":{"type":"string","description":"Product status"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariantResponse"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageResponse"}},"product_type":{"type":"string","description":"Product category"},"vendor":{"type":"string","description":"Brand/vendor name"},"tags":{"type":"string","description":"Comma-separated tags"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"synced":{"type":"boolean","description":"Whether product is synced to Shopify"},"last_synced_at":{"type":"string","format":"date-time","description":"Last sync timestamp"}}},"ProductVariantResponse":{"type":"object","properties":{"id":{"type":"string","description":"Variant ID"},"title":{"type":"string","description":"Variant name"},"sku":{"type":"string","description":"Variant SKU"},"price":{"type":"number","description":"Price in SAR (converted from brand currency)"},"compare_at_price":{"type":"number","description":"Compare at price in SAR"},"inventory_quantity":{"type":"integer","description":"Current stock quantity"},"weight":{"type":"number","description":"Variant weight"},"weight_unit":{"type":"string","description":"Weight unit"},"requires_shipping":{"type":"boolean","description":"Requires shipping"},"taxable":{"type":"boolean","description":"Is taxable"},"barcode":{"type":"string","description":"Product barcode"},"option1":{"type":"string","description":"Option 1 value"},"option2":{"type":"string","description":"Option 2 value"},"option3":{"type":"string","description":"Option 3 value"}}},"ProductImageResponse":{"type":"object","properties":{"id":{"type":"string","description":"Image ID"},"src":{"type":"string","description":"Image URL"},"alt":{"type":"string","description":"Alt text"},"position":{"type":"integer","description":"Display order"}}},"ErrorResponse":{"type":"object","properties":{"error":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","description":"Field that caused the error"},"message":{"type":"string","description":"Human readable error message"}}},{"type":"string","description":"Error message"}]}}},"UpdateProductRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255,"description":"Product name"},"body_html":{"type":"string","maxLength":65535,"description":"Product description (HTML allowed)"},"vendor":{"type":"string","maxLength":255,"description":"Brand/vendor name"},"product_type":{"type":"string","maxLength":255,"description":"Product category"},"tags":{"type":"string","maxLength":1000,"description":"Comma-separated tags"},"handle":{"type":"string","pattern":"^[a-z0-9-]+$","description":"URL slug"},"template_suffix":{"type":"string","maxLength":255,"description":"Template suffix"},"published_scope":{"type":"string","description":"Published scope"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"},"description":"Product variants"},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImage"},"description":"Product images"}},"description":"All fields are optional for updates"},"ProductVariant":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255,"description":"Variant name"},"sku":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Z0-9_-]+$","description":"Unique SKU (alphanumeric, hyphens, underscores)"},"price":{"type":"number","minimum":0,"description":"Price in brand currency"},"compare_at_price":{"type":"number","minimum":0,"description":"Compare at price"},"inventory_quantity":{"type":"integer","minimum":0,"description":"Stock quantity"},"weight":{"type":"number","minimum":0,"description":"Weight in specified unit"},"weight_unit":{"type":"string","maxLength":50,"description":"Weight unit","default":"kg"},"barcode":{"type":"string","maxLength":255,"description":"Product barcode"},"requires_shipping":{"type":"boolean","description":"Requires shipping","default":true},"taxable":{"type":"boolean","description":"Is taxable","default":true}},"required":["title","sku","price","inventory_quantity"]},"ProductImage":{"type":"object","properties":{"src":{"type":"string","format":"uri","description":"Image URL (must be valid URL)"},"alt":{"type":"string","maxLength":500,"description":"Alt text for accessibility"},"position":{"type":"integer","minimum":1,"maximum":100,"description":"Display order"}},"required":["src"]}}},"paths":{"/products/{id}":{"put":{"tags":["Products"],"summary":"Update Product","description":"Updates an existing product. Use external_id for synced products or product_id for unsynced products.","parameters":[{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"Product identifier - external_id (Shopify ID) for synced products, or product_id for unsynced products"}],"responses":{"200":{"description":"Product updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"}}},"required":true}}}}}
```
