https://your-domain.com/api

{
  "success": true,
  "data": { ... },
  "message": "Product created"
}

{
  "success": false,
  "error": "Product not found"
}

curl https://your-domain.com/api/products \
  -H "X-Finxa-Access-Token: fxat_your_secret_key_here"

curl -X POST https://your-domain.com/api/products \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium T-Shirt",
    "status": "ACTIVE",
    "variants": [
      { "title": "Default", "price": 29.99, "inventory": 100 }
    ]
  }'

{
  "success": true,
  "data": {
    "products": [ ... ],
    "pagination": {
      "total": 156,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
}

{
  "success": false,
  "error": "Insufficient scopes. Required: write_products"
}

curl "https://your-domain.com/api/products?status=ACTIVE&limit=10" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "cmmm0ekmc0000ny1p7n1vdsbf",
        "title": "Premium T-Shirt",
        "handle": "premium-t-shirt",
        "status": "ACTIVE",
        "description": "A comfortable cotton t-shirt",
        "vendor": "Finxa Apparel",
        "productType": "Clothing",
        "tags": ["summer", "cotton"],
        "images": [],
        "options": [
          { "name": "Size", "position": 0, "values": ["S", "M", "L"] }
        ],
        "weight": null,
        "weightUnit": "kg",
        "isPhysical": true,
        "seoTitle": null,
        "seoDescription": null,
        "publishedAt": "2026-03-10T12:00:00.000Z",
        "createdAt": "2026-03-10T12:00:00.000Z",
        "updatedAt": "2026-03-10T12:30:00.000Z",
        "variants": [
          {
            "id": "clxyz123",
            "title": "Small",
            "sku": "TS-S",
            "barcode": null,
            "price": "29.990",
            "costPrice": "12.000",
            "compareAtPrice": null,
            "inventory": 50,
            "trackInventory": true,
            "taxable": true,
            "requiresShipping": true,
            "options": { "Size": "S" },
            "position": 0,
            "weight": null,
            "weightUnit": "kg"
          }
        ],
        "productImages": [],
        "_count": { "collections": 1 }
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 10,
      "totalPages": 5
    }
  }
}

curl "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://your-domain.com/api/products" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Polo Shirt",
    "description": "A timeless polo in premium cotton.",
    "status": "ACTIVE",
    "vendor": "Finxa Apparel",
    "productType": "Clothing",
    "tags": ["polo", "cotton", "casual"],
    "options": [
      { "name": "Size", "position": 0, "values": ["S", "M", "L", "XL"] }
    ],
    "variants": [
      { "title": "Small",  "price": 35.00, "sku": "POLO-S",  "inventory": 25, "options": { "Size": "S" } },
      { "title": "Medium", "price": 35.00, "sku": "POLO-M",  "inventory": 40, "options": { "Size": "M" } },
      { "title": "Large",  "price": 35.00, "sku": "POLO-L",  "inventory": 30, "options": { "Size": "L" } },
      { "title": "XL",     "price": 37.50, "sku": "POLO-XL", "inventory": 15, "options": { "Size": "XL" } }
    ]
  }'

curl -X PATCH "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Polo Shirt — Updated",
    "tags": ["polo", "premium", "new-arrival"]
  }'

curl -X DELETE "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "XXL",
    "price": 39.99,
    "sku": "POLO-XXL",
    "inventory": 10,
    "options": { "Size": "XXL" }
  }'

curl -X PATCH "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants/clxyz123" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 32.50,
    "inventory": 75,
    "costPrice": 14.00
  }'

curl -X PUT "https://your-domain.com/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants/sync" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variants": [
      { "id": "existing_id_1", "title": "Small",  "price": 29.99, "inventory": 50 },
      { "id": "existing_id_2", "title": "Medium", "price": 29.99, "inventory": 40 },
      { "title": "Large",  "price": 29.99, "inventory": 30 },
      { "title": "XL",     "price": 34.99, "inventory": 20 }
    ]
  }'

curl "https://your-domain.com/api/collections" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://your-domain.com/api/collections" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Collection 2026",
    "description": "Lightweight essentials for the summer season.",
    "collectionType": "MANUAL",
    "sortOrder": "MANUAL"
  }'

curl -X POST "https://your-domain.com/api/collections/col_abc123/products" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_id_1", "prod_id_2"]
  }'

curl "https://your-domain.com/api/orders?status=PAID&limit=10" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://your-domain.com/api/orders/draft" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "items": [
      { "variantId": "var_xyz789", "quantity": 2 }
    ],
    "shippingAddress": {
      "line1": "123 Main St",
      "city": "Manama",
      "country": "BH"
    }
  }'

curl -X PATCH "https://your-domain.com/api/orders/order_abc123/status" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "FULFILLED" }'

curl -X PATCH "https://your-domain.com/api/orders/order_abc123/notes" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Customer requested gift wrapping" }'

curl -X PATCH "https://your-domain.com/api/orders/order_abc123/shipping" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://track.example.com/1Z999AA10123456784",
    "trackingCarrier": "Aramex"
  }'

curl -X POST "https://your-domain.com/api/customers" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ahmed",
    "lastName": "Al-Khalifa",
    "phone": "+97312345678",
    "address": {
      "line1": "Building 42, Road 3601",
      "city": "Manama",
      "country": "BH",
      "postalCode": "0360"
    }
  }'

curl -X POST "https://your-domain.com/api/discounts" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Sale",
    "code": "SUMMER15",
    "type": "PERCENTAGE",
    "value": 15,
    "minimumOrderAmount": 20,
    "startsAt": "2026-06-01T00:00:00Z",
    "endsAt": "2026-08-31T23:59:59Z"
  }'

curl -X POST "https://your-domain.com/api/shipping/zones" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bahrain Domestic",
    "countries": ["BH"],
    "rates": [
      { "name": "Standard Shipping", "price": 1.500, "minOrderAmount": 0 },
      { "name": "Free Shipping",     "price": 0,     "minOrderAmount": 25 }
    ]
  }'

curl -X POST "https://your-domain.com/api/pages/YOUR_STORE_ID" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "About Us",
    "body": "<h2>Our Story</h2><p>We started in 2024 with a mission to...</p>",
    "published": true
  }'

const API_URL = "https://your-domain.com/api";
const TOKEN = "fxat_your_secret_key_here";

const headers = {
  "X-Finxa-Access-Token": TOKEN,
  "Content-Type": "application/json",
};

// 1. Create a product
async function createProduct() {
  const res = await fetch(`${API_URL}/products`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      title: "My First Product",
      status: "ACTIVE",
      variants: [
        { title: "Default", price: 19.99, inventory: 50 }
      ],
    }),
  });
  const data = await res.json();
  console.log("Created:", data.data.id);
  return data.data;
}

// 2. List all products
async function listProducts() {
  const res = await fetch(`${API_URL}/products`, { headers });
  const data = await res.json();
  console.log(`Found ${data.data.pagination.total} products`);
  return data.data.products;
}

// 3. Update a product
async function updateProduct(productId) {
  const res = await fetch(`${API_URL}/products/${productId}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({
      description: "Updated via the API!",
      tags: ["api-managed"],
    }),
  });
  const data = await res.json();
  console.log("Updated:", data.data.title);
}

// Run it
const product = await createProduct();
await updateProduct(product.id);
await listProducts();

import requests

API_URL = "https://your-domain.com/api"
HEADERS = {
    "X-Finxa-Access-Token": "fxat_your_secret_key_here",
    "Content-Type": "application/json",
}

# Create a product
res = requests.post(f"{API_URL}/products", headers=HEADERS, json={
    "title": "My First Product",
    "status": "ACTIVE",
    "variants": [
        {"title": "Default", "price": 19.99, "inventory": 50}
    ],
})
product = res.json()["data"]
print(f"Created: {product['id']}")

# List all products
res = requests.get(f"{API_URL}/products", headers=HEADERS)
data = res.json()["data"]
print(f"Found {data['pagination']['total']} products")

# Update a product
res = requests.patch(f"{API_URL}/products/{product['id']}", headers=HEADERS, json={
    "description": "Updated via the API!",
    "tags": ["api-managed"],
})
print(f"Updated: {res.json()['data']['title']}")