sapo-mcp

List smart (rule-based) collections. For SEO/content team: view auto-generated collections

Add a new address to a customer. Required: address1, city, country.

List refunds for a specific order. Returns full refund records with associated transactions, refund line items, and order adjustments.

Get a single refund by ID. Returns full refund record.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] List POS shifts (cash drawer sessions). For store owners — view opening/closing cash balances per shift. Returns paginated results via since_id cursor.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] Get a single POS shift by ID. Returns opening/closing amounts, status, and timing.

Adjust inventory level by a relative delta (positive = receive stock, negative = remove stock). For inventory managers — use for stock receipts and corrections. Delta is applied atomically.

Connect an inventory item to a location (enable tracking at that location). For store owners — run once per item per location to activate inventory tracking.

List all saved addresses for a customer, including default address flag and Vietnamese province/district/ward fields.

Update an existing customer address. Only provided fields are modified.

Set a customer's default address via Sapo's dedicated endpoint

List articles within a specific blog. For SEO/content team: browse articles to review

Get a single article by ID within a blog. Returns full HTML body, SEO fields,

Create a new article within a blog. For SEO/content team: provide title, HTML body,

Update an existing article. For SEO/content team: update title, body, SEO fields,

List Vietnamese provinces. Default (omit level) = level=3 = pre-2025 63 tỉnh, 3-tier.

List districts (Quận/Huyện) within a province. Only meaningful for level=3

List wards (Phường/Xã). For level=3 (default, 3-tier) pass district_code obtained from

Aggregate order revenue grouped by day/week/month within a date range. Returns groups with total_revenue (VND), order_count, avg_order_value plus overall totals.

Top selling products by revenue or quantity within a date range, walking line_items across all matching orders.

Top customers ranked by total revenue or order count within a date range. Guests grouped by email/phone.

Lifetime value for a single customer: total revenue, order count, first/last order date.

Inventory levels with available stock below a threshold, sorted ascending.

Total inventory value (Σ available × variant.price) optionally scoped to a location. Variants without price data are reported under missing_price_count.

Tax totals over a date range, broken down by tax rate.

Compare physical POS counter sales vs online sales within a date range. Counter = source_name in {"pos", "pos_counter"}; everything else is online.

Discount code usage within a date range: per-code order count, total discount amount, total revenue. Filter by code if specified.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] Shift summary: orders count, total revenue, breakdown by payment method. Cashbook NOT included (internal-only endpoint).

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] List suppliers. For inventory managers and store owners — view vendors and supply contacts. Returns paginated results via since_id cursor.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] Get a single supplier by ID. Returns contact details and address.

List price rules (discount rules) with optional filters. Returns paginated results via since_id cursor. Filter by status (active, archived, scheduled).

Get a single price rule by ID. Returns full price rule including value_type, value (string), entitled/prerequisite IDs, and usage stats.

Create a new price rule (discount rule). Side effect: creates a PriceRule record. value must be a STRING (e.g. "-10.0" for 10% off). title, value_type, value, target_type, allocation_method, customer_selection, target_selection are required.

Update an existing price rule. Side effect: modifies the price rule. Only provided fields are updated. value must remain a string if updating.

Update a product variant (price, compare_at_price, SKU, barcode, weight). For store owners / inventory managers. Provide only the fields you want to change.

List customers with optional filters. Returns paginated results via since_id cursor. If has_more=true, call again with next_since_id.

Get a single customer by ID, including their address list and order count.

Search customers by query string (matches email, phone, name). Returns paginated list.

Count total customers in the store, optionally filtered by creation date.

List all orders placed by a specific customer. Returns paginated results via since_id cursor.

Create a new customer. Must provide either email OR phone (or both).

Update an existing customer. Only provided fields are modified.

List orders created at the POS counter (source_name=pos). For cashiers — review in-store sales. Returns paginated results via since_id cursor.

Get a single POS order by ID. For cashiers — view full details of an in-store transaction including line items, payment, and fulfillment status.

List all variants for a product (SKUs, prices in VND, inventory quantities). Returns paginated results via since_id cursor.

Get a single product variant by ID. Returns price (VND, float with 4 decimals), SKU, barcode, inventory quantity, and option values.

List all script tags injected into the storefront. For SEO/content team:

Inject a new JavaScript file into the storefront. For SEO/content team:

List all storefront pages. For SEO/content team: browse pages to audit SEO metadata,

Get a single storefront page by ID, including its body_html, SEO meta fields,

SEO-only update for a storefront page. For SEO/content team: update meta_title,

List all transactions for a specific order. Returns payment attempts, captures, refunds, and voids linked to the order.

Create a transaction for an order (e.g. capture, sale, refund). Side effect: creates a Transaction record and may change order financial_status. kind: authorization | capture | sale | void | refund.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] List stock transfers between locations. For inventory managers — track goods movement between warehouses and retail counters. Returns paginated results via since_id cursor.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] Get a single stock transfer by ID. Returns source/destination locations, status, and line items.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] List all configured payment methods for the store (cash, bank transfer, card, etc). For cashiers — use to display payment options at POS counter.

List products with optional filters (status, vendor, product_type). Returns paginated results via since_id cursor. If has_more=true, call again with next_since_id.

Get a single product by ID, including its variants, options, and images.

Search products by title substring. Uses the title filter on the list endpoint. Returns paginated results.

Count total products in the store, optionally filtered by status, vendor, or product_type.

List draft orders with optional filters. Returns paginated results via since_id cursor. Filter by status. If has_more=true, call again with next_since_id.

Get a single draft order by ID. Returns full draft order including line_items, customer, address, and applied discounts.

Create a new draft order. Side effect: creates a DraftOrder in "open" status. Requires at least one line_item with variant_id or title+price for custom items.

Update a draft order in "open" status. Side effect: modifies draft order fields. Cannot update completed or cancelled drafts.

Complete a draft order and convert it into a real order. Side effect: creates an Order from the draft; draft status becomes "completed". Use payment_pending=true if payment not yet collected.

Send an invoice email for a draft order. Side effect: sends email to customer; draft status becomes "invoice_sent". Requires customer email on the draft or provide via to param.

Get inventory levels (available + committed quantities) for specific variants at specific locations. Filter by location_id, inventory_item_id, or both.

List all blogs in the store. For SEO/content team: browse blogs to manage article

Get a single blog by ID, including its handle, commentable setting, and tag metadata.

Create a new blog. For SEO/content team: set title, handle (URL slug),

Update a blog. For SEO/content team: rename, change handle/slug, or adjust comment policy.

List discount codes for a specific price rule. Returns paginated results via since_id cursor. Must provide price_rule_id.

Create a discount code for a price rule. Side effect: creates a DiscountCode that customers can apply at checkout. Code must be unique across the store.

Get Sapo store information: name, domain, address, currency, timezone, owner.

SEO-only update for a product: set meta_title, meta_description, URL slug, and tags.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] List all store locations (warehouses, retail counters). For inventory managers — use location_id to filter inventory queries per location.

[UNDOCUMENTED endpoint, verified 2026-04-30, schema may change] Get a single location by ID. Returns address, contact info, and active status.

List orders with optional filters. Returns paginated results via since_id cursor. Filter by status, financial_status, fulfillment_status, or source_name (facebook, web, pos). If has_more=true, call again with next_since_id.

Get a single order by ID. Returns full order including line_items, fulfillments, customer, billing/shipping address, and financial details.

Count total orders, optionally filtered by status, financial_status, or date range. Returns { count: N }.

Search orders by name (order #), customer email, or customer phone. Uses filter params on the orders list endpoint. Returns paginated results.

Update an existing order via PUT /admin/orders/{id}.json. Supports: tags, note,

List all fulfillments for a specific order. Returns fulfillment records with tracking info, line_items, and delivery status.

Get a single fulfillment by ID. Returns full fulfillment with tracking info, line_items, and origin address.

Create a fulfillment for an order, optionally specifying line items and tracking info. Side effect: creates a Fulfillment record and marks specified line_items as fulfilled.

Update tracking information for an existing fulfillment. Side effect: modifies the Fulfillment tracking_company, tracking_number, or tracking_url.

List custom (manual) collections. For SEO/content team: use to browse collections

Get a single custom collection by ID, including its body_html, sort_order, image, and SEO fields.

Create a new custom (manual) collection. For SEO/content team: set title, body_html,

Update a custom collection. For SEO/content team: update title, body_html,

Get a single smart collection by ID, including its matching rules and SEO fields.

List product-to-collection mappings (collects).

Add a product to a custom collection by creating a collect mapping.