Sapo MCP by usefulapi

The Sapo store this login belongs to: name, domain, currency, timezone, plan and other settings. GET /admin/store.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List products with their variants, prices, SKUs and images. Filter by name, vendor, type, collection or created/modified dates. Paged: pass next_page as page. GET /admin/products.json.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search by product name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "ids": {
      "description": "Only these product ids.",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "vendor": {
      "description": "Exact vendor (brand) name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_type": {
      "description": "Exact product type.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "collection_id": {
      "description": "Only products in this collection (see sapo_list_custom_collections).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "since_id": {
      "description": "Only products with an id greater than this.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Number of products matching the filters. GET /admin/products/count.json.

{
  "type": "object",
  "properties": {
    "vendor": {
      "description": "Exact vendor (brand) name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_type": {
      "description": "Exact product type.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "collection_id": {
      "description": "Only products in this collection (see sapo_list_custom_collections).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product by id, with variants and images. GET /admin/products/{id}.json.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo product id."
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The variants (size, color, SKU, barcode, price) of one product. Paged. GET /admin/products/{product_id}/variants.json.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo product id."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product variant by id. GET /admin/variants/{id}.json.

{
  "type": "object",
  "properties": {
    "variant_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo variant id."
    }
  },
  "required": [
    "variant_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List manual product collections (danh mục thủ công). Paged. GET /admin/custom_collections.json.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Filter by collection name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_id": {
      "description": "Only collections that contain this product.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List orders with line items, customer, totals, payment and fulfillment status. Filter by status, tag, customer or dates. Paged: pass next_page as page. GET /admin/orders.json.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search text (order number, customer name, phone, email).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "status": {
      "description": "Order status: open (Sapo default when omitted, so archived orders are left out), closed, or any (all orders). Pass any for date-range totals.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "financial_status": {
      "description": "Payment status: authorized, pending, paid, refunded, voided, or any. Sapo default when omitted: authorized, pending and paid only (refunded and voided are left out).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "fulfillment_status": {
      "description": "Fulfillment status (for example unfulfilled, fulfilled, partial).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "tag": {
      "description": "Only orders with this tag.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "customer_id": {
      "description": "Only orders of this customer.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Number of orders matching the filters. GET /admin/orders/count.json.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Order status: open (Sapo default when omitted, so archived orders are left out), closed, or any (all orders). Pass any for date-range totals.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "financial_status": {
      "description": "Payment status: authorized, pending, paid, refunded, voided, or any. Sapo default when omitted: authorized, pending and paid only (refunded and voided are left out).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "fulfillment_status": {
      "description": "Fulfillment status (for example unfulfilled, fulfilled, partial).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One order by id with line items, addresses, discounts, payment and shipping. GET /admin/orders/{id}.json.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo order id."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The payment transactions recorded on one order. GET /admin/orders/{order_id}/transactions.json.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo order id."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customers with contact details, addresses, order count and total spent. Paged. GET /admin/customers.json.

{
  "type": "object",
  "properties": {
    "since_id": {
      "description": "Only customers with an id greater than this.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "modified_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Total number of customers. GET /admin/customers/count.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by id. GET /admin/customers/{id}.json.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo customer id."
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List branches, stores and warehouses (id, name, address, whether they track stock). Use the ids for stock levels. Paged. GET /admin/locations.json.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search by name, code or phone.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "status": {
      "description": "Branch status; Sapo spells the inactive value \"expried\".",
      "type": "string",
      "enum": [
        "active",
        "expried"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List inventory items (one per variant) by SKU/barcode search, variant or product ids. The id is what stock levels use as inventory_item_id. Paged. GET /admin/inventory_items.json.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search by barcode or SKU.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "variant_ids": {
      "description": "Only these variant ids.",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "product_ids": {
      "description": "Only these product ids.",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "ids": {
      "description": "Only these inventory item ids.",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Stock per item and location: on_hand, available, committed, incoming, reserved. Filter by inventory item or location ids, or by a minimum/maximum available quantity. Sapo documents no paging for this list, so narrow it with ids. GET /admin/inventory_levels.json.

{
  "type": "object",
  "properties": {
    "inventory_item_ids": {
      "description": "Only these inventory item ids (see sapo_list_inventory_items).",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "location_ids": {
      "description": "Only these location ids (see sapo_list_locations).",
      "minItems": 1,
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "available_min": {
      "description": "Only levels with at least this much available.",
      "type": "number"
    },
    "available_max": {
      "description": "Only levels with at most this much available.",
      "type": "number"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List discount price rules (percentage, fixed amount, fixed price) with validity dates and usage counts. Paged. GET /admin/price_rules.json.

{
  "type": "object",
  "properties": {
    "created_on_min": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "created_on_max": {
      "type": "string",
      "description": "ISO 8601 date or date-time (UTC unless it carries an offset), e.g. 2026-10-01 or 2026-10-01T00:00:00Z."
    },
    "starts_on_min": {
      "description": "Only rules that start on or after this date.",
      "type": "string"
    },
    "starts_on_max": {
      "description": "Only rules that start on or before this date.",
      "type": "string"
    },
    "ends_on_min": {
      "description": "Only rules that end on or after this date.",
      "type": "string"
    },
    "ends_on_max": {
      "description": "Only rules that end on or before this date.",
      "type": "string"
    },
    "times_used": {
      "description": "Only rules used exactly this many times.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "limit": {
      "description": "Results per page, 1-250 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 250
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: set the note and/or the tags of an order (Sapo only lets an order's items and quantities stay fixed after creation). The value REPLACES the existing note or tags: read the order first to keep what is there. PUT /admin/orders/{id}.json.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sapo order id."
    },
    "note": {
      "description": "New order note (replaces the old one; empty string clears it).",
      "type": "string",
      "maxLength": 5000
    },
    "tags": {
      "description": "New tag list (replaces all tags; an empty list clears them).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: set the physical stock (on_hand) of one inventory item at one location to an exact quantity, with a reason. This OVERWRITES the current number and is recorded as a stock adjustment: read the level first (sapo_list_inventory_levels). PUT /admin/inventory_levels/set.json.

{
  "type": "object",
  "properties": {
    "inventory_item_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Inventory item id (see sapo_list_inventory_items)."
    },
    "location_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Location id (see sapo_list_locations)."
    },
    "on_hand": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000,
      "description": "Physical on-hand quantity to set (at most 3 decimals are kept)."
    },
    "reason": {
      "description": "Why the stock changes (default: Sapo's own default).",
      "type": "string",
      "enum": [
        "inventory_change_by_damaged",
        "inventory_change_by_return_restock",
        "inventory_change_by_transfer",
        "inventory_change_by_manufacture",
        "inventory_change_by_loss",
        "inventory_change_by_correction",
        "inventory_change_by_other_reason"
      ]
    }
  },
  "required": [
    "inventory_item_id",
    "location_id",
    "on_hand"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}