Products | Maison Safqa API v1

Create Product

post

Creates a new product in draft status. The product will be synced to Shopify when activated. SKUs must be unique within your brand.

Authorizations

X-MaisonSafqa-Api-KeystringRequired

API key for authentication. Use 'ms_test_...' keys for development/testing and 'ms_live_...' keys for production. Keys are environment-specific and will only work in their respective environments.

Body

titlestring · min: 1 · max: 255Required

Product name

Example: Premium Cotton T-Shirt

body_htmlstring · max: 65535Optional

Product description (HTML allowed)

Example: <p>High quality cotton t-shirt perfect for everyday wear.</p>

vendorstring · max: 255Optional

Brand/vendor name

Example: Your Brand Name

product_typestring · max: 255Optional

Product category

Example: Apparel

tagsstring · max: 1000Optional

Comma-separated tags

Example: cotton,premium,t-shirt,comfortable

handlestringOptional

URL slug (auto-generated if not provided)

Example: premium-cotton-t-shirtPattern: ^[a-z0-9-]+$

template_suffixstring · max: 255Optional

Template suffix

published_scopestringOptional

Published scope

Default: web

Responses

201

Product created successfully

application/json

400

Validation errors or duplicate SKUs

application/json

401

Unauthorized - Invalid or missing API key

application/json

403

Forbidden - Access denied

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/products

POST /v1/products HTTP/1.1
Host: api.maisonsafqa.com
X-MaisonSafqa-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 613

{
  "title": "Premium Cotton T-Shirt",
  "body_html": "<p>High quality cotton t-shirt perfect for everyday wear.</p>",
  "vendor": "Your Brand Name",
  "product_type": "Apparel",
  "tags": "cotton,premium,t-shirt,comfortable",
  "handle": "premium-cotton-t-shirt",
  "template_suffix": "text",
  "published_scope": "web",
  "variants": [
    {
      "title": "Medium",
      "sku": "COTTON-TEE-001-M",
      "price": 99.99,
      "compare_at_price": 149.99,
      "inventory_quantity": 25,
      "weight": 0.2,
      "weight_unit": "kg",
      "barcode": "1234567890123",
      "requires_shipping": true,
      "taxable": true
    }
  ],
  "images": [
    {
      "src": "https://example.com/images/tshirt-front.jpg",
      "alt": "T-shirt front view",
      "position": 1
    }
  ]
}

{
  "error": null,
  "product": null,
  "message": "Product created successfully. It will be synced to Shopify when activated."
}

Get Product

get

Retrieves a specific product by its product_id. Only products belonging to the authenticated brand can be accessed.

Authorizations

X-MaisonSafqa-Api-KeystringRequired

API key for authentication. Use 'ms_test_...' keys for development/testing and 'ms_live_...' keys for production. Keys are environment-specific and will only work in their respective environments.

Path parameters

product_idstringRequired

Product identifier (format: product_XXXXXXXXXXXXXXXX)

Example: {"value":"product_1234567890123456"}

Responses

200

Product retrieved successfully

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Product not found or does not belong to your brand

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

get

/products/{product_id}

GET /v1/products/{product_id} HTTP/1.1
Host: api.maisonsafqa.com
X-MaisonSafqa-Api-Key: YOUR_API_KEY
Accept: */*

{
  "error": null,
  "product": null
}

Update Product

put

Updates an existing product. All fields are optional - only provided fields will be updated. Only products belonging to the authenticated brand can be modified.

Authorizations

X-MaisonSafqa-Api-KeystringRequired

API key for authentication. Use 'ms_test_...' keys for development/testing and 'ms_live_...' keys for production. Keys are environment-specific and will only work in their respective environments.

Path parameters

product_idstringRequired

Product identifier (format: product_XXXXXXXXXXXXXXXX)

Example: {"value":"product_1234567890123456"}

Body

All fields are optional for updates

titlestring · min: 1 · max: 255Optional

Product name

body_htmlstring · max: 65535Optional

Product description (HTML allowed)

vendorstring · max: 255Optional

Brand/vendor name

product_typestring · max: 255Optional

Product category

tagsstring · max: 1000Optional

Comma-separated tags

handlestringOptional

URL slug

Pattern: ^[a-z0-9-]+$

template_suffixstring · max: 255Optional

Template suffix

published_scopestringOptional

Published scope

Responses

200

Product updated successfully

application/json

400

Validation errors or duplicate SKUs

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Product not found or does not belong to your brand

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

put

/products/{product_id}

PUT /v1/products/{product_id} HTTP/1.1
Host: api.maisonsafqa.com
X-MaisonSafqa-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 477

{
  "title": "text",
  "body_html": "text",
  "vendor": "text",
  "product_type": "text",
  "tags": "text",
  "handle": "text",
  "template_suffix": "text",
  "published_scope": "text",
  "variants": [
    {
      "title": "Medium",
      "sku": "COTTON-TEE-001-M",
      "price": 99.99,
      "compare_at_price": 149.99,
      "inventory_quantity": 25,
      "weight": 0.2,
      "weight_unit": "kg",
      "barcode": "1234567890123",
      "requires_shipping": true,
      "taxable": true
    }
  ],
  "images": [
    {
      "src": "https://example.com/images/tshirt-front.jpg",
      "alt": "T-shirt front view",
      "position": 1
    }
  ]
}

{
  "error": null,
  "product": null,
  "message": "Product updated successfully"
}

Bulk Create Products

post

Creates multiple products in a single request. Maximum 500 products per request. Partial success is supported - valid products will be created even if some fail validation.

Authorizations

X-MaisonSafqa-Api-KeystringRequired

API key for authentication. Use 'ms_test_...' keys for development/testing and 'ms_live_...' keys for production. Keys are environment-specific and will only work in their respective environments.

Body

Responses

201

All products created successfully

application/json

207

Partial success - some products created, some failed

application/json

400

Validation errors

application/json

401

Unauthorized

application/json

429

Rate limit exceeded

application/json

post

/products/bulk

POST /v1/products/bulk HTTP/1.1
Host: api.maisonsafqa.com
X-MaisonSafqa-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "products": [
    {
      "title": "Premium Cotton T-Shirt",
      "body_html": "<p>High quality cotton t-shirt perfect for everyday wear.</p>",
      "vendor": "Your Brand Name",
      "product_type": "Apparel",
      "tags": "cotton,premium,t-shirt,comfortable",
      "handle": "premium-cotton-t-shirt",
      "template_suffix": "text",
      "published_scope": "web",
      "variants": [
        {
          "title": "Medium",
          "sku": "COTTON-TEE-001-M",
          "price": 99.99,
          "compare_at_price": 149.99,
          "inventory_quantity": 25,
          "weight": 0.2,
          "weight_unit": "kg",
          "barcode": "1234567890123",
          "requires_shipping": true,
          "taxable": true
        }
      ],
      "images": [
        {
          "src": "https://example.com/images/tshirt-front.jpg",
          "alt": "T-shirt front view",
          "position": 1
        }
      ]
    }
  ]
}

{
  "success": true,
  "message": "47 of 50 products created successfully",
  "created": [
    {
      "product_id": "product_1234567890123456",
      "title": "text"
    }
  ],
  "failed": [
    {
      "index": 2,
      "title": "Premium Cotton T-Shirt",
      "errors": [
        {
          "field": "variants.sku",
          "message": "SKUs already exist for this brand: SKU-001"
        }
      ]
    }
  ]
}

Good evening

Create Product

Get Product

Update Product

Bulk Create Products