Shop API

Building a shop: best practices

This order avoids rework: settings and structure first, then the catalogue, then merchandising, then a real test order. It works the same through the REST API, the MCP tools or the dashboard.

1. Settings before products

• Set currency_code and currency_symbol together in shop settings. Prices are stored as numbers in that currency.
• Create shipping zones with their rates, and the tax rates by destination country, before the first order so checkout totals are right from day one.
• Choose the payment methods: card (Stripe Checkout) and/or bank transfer with payment_instructions.

2. Structure: categories and custom fields

• Build the category tree first; 2–3 levels is enough for most shops. A product belongs to one category, and filtering by a parent includes its children.
• Create the custom field definitions before importing products: values for undefined keys are rejected.
• Use one namespace for the data shoppers compare (specs, defined with storefront_visible: true: definitions are private by default) and another for internal data (internal, with storefront_visible: false). Keys are lowercase: specs.ram.
• Pick the most specific type: weight, dimension or volume for measures (filters convert units), integer with validations.unit for values like "16 GB", list.single_line_text for several values (connectivity, colours), boolean for yes/no.
• Mark as filterable only what shoppers really filter by (brand, size, main specs; usually 4–8 fields). Every filterable field becomes a facet in the filter sidebar.
• Never put private data (cost, supplier, margins) in a storefront-visible field: the storefront API is public.

3. The catalogue

• Give every product a stable slug and a unique SKU; URLs and integrations rely on them.
• Use variants for options of the same product (size, colour, capacity) instead of separate products. Stock is tracked per variant.
• Fill meta_title, meta_description, a real description and vendor (brand): they feed SEO, structured data and the brand facet.
• Upload a main image and a gallery with the same aspect ratio (square works best in grids), at least 1000 px wide.
• Import in batches with products/bulk/ (up to 100 per call) including metafields, or set values afterwards with metafields/set/ (up to 250, atomic).
• Moving from free-form technical_specs? Run metafield-definitions/suggest/, create the definitions, then call import/ with dry_run: true first and review skipped.

4. Merchandising

• Prefer automatic collections (rules on price, vendor, tags, category or custom fields) over manual lists: they stay up to date as the catalogue changes.
• Feature a few products, and use automatic discounts or coupon codes for promotions instead of editing prices.

5. Integrations and custom storefronts

• Use PATCH with only the fields you change, and send If-Match with the ETag you read when several people or systems edit the same product.
• For calls that add or move an amount (gift card adjust, order edits, refunds, completing a draft), MCP clients pass an idempotency_key (one unique string per intended operation): a retry with the same key returns the first result and is never applied twice.
• Give every product a unique SKU. Creating a product whose SKU (or explicit slug) already exists answers 409 with the existing id in REST, and returns the existing product with already_existed: true in MCP, so retries and re-imports never duplicate it. Look products up with ?search= (name, SKU or slug).
• Keep external copies in sync with updated_since (changes) plus products/deleted/?since= (deletions) instead of downloading the whole catalogue again.
• Build filter sidebars from facets=1 and show values with their display field. Always escape text from the API before inserting it into HTML.
• Respect Cache-Control and, on a 503, wait the Retry-After seconds before retrying.
• Subscribe to order webhooks instead of polling the orders list.

6. Before launch

• Place a real test order for each payment method and shipping zone, and check the emails, stock and totals (shipping and tax).
• Open a product page on a phone: images, specifications table, variant selector and add to cart.
• Publish the legal pages (terms, privacy, returns) and, if you accept returns, enable them in shop settings.

API conventions

Management endpoints live under https://escalateflow.com/api/v1/projects/{project_id}/ and need an API key: Authorization: Bearer ef_live_… (or X-API-Key). Every schema is in Swagger.

412 example

{
  "success": false,
  "error": {
    "code": 412,
    "message": "The resource changed since you read it (If-Match does not match): GET it again, re-apply your change and retry with the new ETag",
    "current_etag": "\"65e290601f600\""
  }
}

Products

{
  "success": true,
  "products": [
    {
      "id": "uuid",
      "name": "Premium T-Shirt",
      "slug": "premium-t-shirt",
      "price": "29.99",
      "formatted_price": "29,99 €",
      "sku": "TSH-001",
      "vendor": "Acme",
      "stock_quantity": 100,
      "is_in_stock": true,
      "category": "uuid",
      "category_name": "Apparel",
      "metafields": {"specs.material": "Organic cotton", "specs.peso": {"value": 200, "unit": "g"}},
      "has_variants": true,
      "url": "https://my-store.escalateflow.com/shop/product/premium-t-shirt/",
      "updated_at": "2026-10-19T10:02:11Z"
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

{
  "name": "Premium T-Shirt",
  "slug": "premium-t-shirt",
  "description": "100% organic cotton t-shirt",
  "price": "29.99",
  "compare_at_price": "39.99",
  "sku": "TSH-001",
  "vendor": "Acme",
  "category_id": "uuid",
  "track_inventory": true,
  "stock_quantity": 100,
  "meta_title": "Premium organic T-Shirt",
  "meta_description": "Soft 200 g organic cotton tee.",
  "is_active": true,
  "metafields": {
    "specs.material": "Organic cotton",
    "specs.peso": {"value": 200, "unit": "g"}
  }
}

curl -X PATCH "https://escalateflow.com/api/v1/projects/{project_id}/products/{product_id}/" \
  -H "Authorization: Bearer ef_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "65e290601f600"' \
  -d '{"price": "24.99", "metafields": {"specs.peso": {"value": 210, "unit": "g"}}}'

Product Variants

{
  "title": "Large / Blue",
  "sku": "TSH-001-LG-BL",
  "price": "29.99",
  "stock_quantity": 25,
  "metafields": {"specs.color_hex": "#1a3d8f"}
}

Categories

{
  "name": "Apparel",
  "slug": "apparel",
  "description": "Clothing and accessories",
  "parent_id": null
}

Custom fields (metafields)

Typed fields you define once and fill on products, variants or collections: RAM, weight, material, warranty… They are validated, shown in the product page's specifications table (custom fields first, in position order, then the free-form technical_specs rows they don't replace), and can be used as storefront filters and facets.

curl -X POST "https://escalateflow.com/api/v1/projects/{project_id}/metafield-definitions/" \
  -H "Authorization: Bearer ef_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "specs", "key": "ram", "name": "RAM", "type": "integer",
       "validations": {"unit": "GB", "min": 1}, "storefront_visible": true, "filterable": true}'

{
  "metafields": [
    {"owner_type": "product", "owner_id": "uuid", "key": "specs.ram", "value": 32},
    {"owner_type": "product", "owner_id": "uuid", "key": "specs.peso", "value": {"value": 1.09, "unit": "kg"}},
    {"owner_type": "variant", "owner_id": "uuid", "key": "specs.color_hex", "value": "#1a1a1a"}
  ]
}

{
  "success": false,
  "error": {
    "code": 400,
    "message": "metafields: specs.ram: must be a number",
    "details": {"metafields": {"specs.ram": "specs.ram: must be a number"}}
  }
}

{
  "source": "technical_specs",
  "mapping": {"socket": "specs.socket", "weight": "specs.peso"},
  "overwrite": false,
  "remove_source": false,
  "dry_run": true
}

Collections

{
  "title": "Light mice",
  "slug": "light-mice",
  "kind": "automatic",
  "rules": {"match": "all", "conditions": [
    {"field": "category", "op": "equals", "value": "mice"},
    {"field": "metafield", "key": "specs.peso", "op": "lte", "value": 80}
  ]}
}

Storefront API (public)

A read-only catalogue for custom storefronts, apps and search: GET https://{your-shop-domain}/api/v1/public/{project_id}/…. No key is needed, and it only returns active products and storefront-visible custom fields. Calls from another origin are allowed for the shop's own domains and the origins listed in api_allowed_origins (shop settings).

{
  "products": [
    {"id": "uuid", "name": "Superlight 2", "slug": "superlight-2", "url": "https://…", "price": "149.00",
     "price_formatted": "149,00 €", "image_url": "https://…", "category": "Mice", "category_slug": "mice",
     "vendor": "Logitech", "in_stock": true}
  ],
  "count": 34,
  "facets": {
    "vendors": [{"name": "Logitech", "count": 12}],
    "categories": [{"name": "Mice", "slug": "mice", "count": 34}],
    "price": {"min": "19.00", "max": "179.00"},
    "in_stock": 31,
    "metafields": {
      "specs.peso": {"name": "Peso", "type": "weight", "unit": "g", "min": 54, "max": 141,
                     "values": [{"value": {"value": 60, "unit": "g"}, "display": "60 g", "count": 3}]},
      "specs.conexion": {"name": "Conexión", "type": "list.single_line_text",
                         "values": [{"value": "USB-C", "display": "USB-C", "count": 20}]}
    }
  }
}

"metafields": {
  "specs": {
    "ram":  {"name": "RAM", "type": "integer", "value": 32, "display": "32 GB", "unit": "GB"},
    "peso": {"name": "Peso", "type": "weight", "value": {"value": 1.09, "unit": "kg"}, "display": "1,09 kg"}
  }
}

Orders & checkout

All under /api/v1/projects/{project_id}/. Request and response schemas are in Swagger, and each area also has MCP tools.

Shop Settings & Pages

{
  "success": true,
  "data": {
    "is_enabled": true,
    "currency_code": "PYG",
    "currency_symbol": "Gs.",
    "supported_currencies": [],
    "layout": "grid",
    "products_per_page": 12,
    "show_categories": true,
    "url_prefix": "shop",
    "product_base": "product",
    "category_base": "category",
    "shop_url": "https://subdomain.escalateflow.com/shop/"
  }
}

curl -X PUT "https://escalateflow.com/api/v1/projects/{id}/shop/settings/" \
  -H "Authorization: Bearer ef_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "currency_code": "PYG",
    "currency_symbol": "Gs.",
    "is_enabled": true,
    "shop_title": "Mi Tienda"
  }'

Storefront Cart API

Session-based cart endpoints for the public storefront. These run on the shop subdomain, not the main API.

curl -X POST "https://my-store.escalateflow.com/shop/cart/add/{product_id}/" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 2}'

{
  "success": true,
  "items": [
    {
      "id": "uuid",
      "name": "Smart TV Samsung 55\" 4K",
      "slug": "smart-tv-samsung-55-4k",
      "price": "4290000.00",
      "price_formatted": "Gs. 4.290.000",
      "image_url": "https://...",
      "quantity": 2,
      "line_total": "8580000.00",
      "line_total_formatted": "Gs. 8.580.000"
    }
  ],
  "item_count": 1,
  "cart_count": 2,
  "subtotal": "8580000.00",
  "subtotal_formatted": "Gs. 8.580.000",
  "currency_symbol": "Gs."
}

Shop Hero Slides

{
  "title": "Summer Collection",
  "subtitle": "Up to 50% off",
  "image_url": "https://...",
  "cta_text": "Shop Now",
  "cta_url": "/shop/summer"
}