Getting Started

Welcome to the Maison Safqa Brand Developer API. This API allows you to programmatically manage your products on the Maison Safqa platform

Base URL

All API requests should be made to:

https://api.maisonsafqa.com/v1

Authentication

All API endpoints require authentication using an API key. Include your API key in the X-MaisonSafqa-Api-Key header with every request.

API Key Formats

Environment	Key Prefix	Usage
Development	ms_test_...	Testing and development only
Production	ms_live_...	Live production environment

⚠️ Important: API keys are environment-specific. A test key will not work in production, and vice versa.

Getting Your API Key

Contact the Maison Safqa team at [email protected] to request API access for your brand.

When you receive your API key, store it securely. The full key is only shown once at creation time.

Quick Start Example

Here's a simple example to create your first product:

curl -X POST https://api.maisonsafqa.com/v1/products \
  -H "Content-Type: application/json" \
  -H "X-MaisonSafqa-Api-Key: ms_test_your_api_key_here" \
  -d '{
    "title": "Premium Cotton T-Shirt",
    "body_html": "<p>High quality cotton t-shirt.</p>",
    "vendor": "Your Brand Name",
    "product_type": "Apparel",
    "tags": "cotton,premium,t-shirt",
    "variants": [
      {
        "title": "Small",
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      },
      {
        "title": "Medium",
        "sku": "TSHIRT-001-M",
        "price": 99.99,
        "inventory_quantity": 50
      },
      {
        "title": "Large",
        "sku": "TSHIRT-001-L",
        "price": 99.99,
        "inventory_quantity": 30
      }
    ],
    "images": [
      {
        "src": "https://example.com/images/tshirt-front.jpg",
        "alt": "T-shirt front view",
        "position": 1
      }
    ]
  }'

Response

A successful response returns status 201 Created:

{
  "error": null,
  "product": {
    "id": "product_1234567890123456",
    "title": "Premium Cotton T-Shirt",
    "handle": "premium-cotton-t-shirt",
    "status": "draft",
    "variants": [
      {
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      }
    ],
    "synced": false,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Product created successfully. It will be synced to Shopify when activated."
}

Rate Limits

The API enforces rate limiting to ensure fair usage:

Limit	Value
Requests per minute	300
Bulk operation max items	500

Rate Limit Headers

Every response includes rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute (300)
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the limit resets

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Key Concepts

Product Status

Products are created in draft status and will be synced to Shopify when activated by the Maison Safqa team.

Inventory Sync

Inventory updates are stored locally and periodically synced to Shopify. Your brand's inventory data always takes precedence in case of conflicts.

Bulk Operations

For efficiency, you can create up to 500 products or update inventory for up to 500 products in a single request. Bulk operations support partial success - valid items are processed even if some fail validation.

Error Handling

All errors follow a consistent format:

{
  "error": {
    "field": "variants.sku",
    "message": "SKUs already exist for this brand: TSHIRT-001-S"
  }
}

Common HTTP status codes:

Code	Description
200	Success
201	Created
207	Multi-Status (partial success in bulk operations)
400	Bad Request - Validation errors
401	Unauthorized - Invalid or missing API key
404	Not Found - Product doesn't exist or doesn't belong to your brand
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Next Steps

• Products API - Create, retrieve, and update products

• Inventory API - Manage inventory levels

• Error Reference - Complete list of error codes and messages

Support

If you have questions or need assistance:

• Email: [email protected]

• Documentation Issues: Open an issue on our developer portal