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). Optionally include addresses array for inline address creation. Returns the created customer including auto-generated id.

Update an existing customer. Only provided fields are modified. Use add_customer_address / update_customer_address tools for address management.

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

Add a new address to a customer. Required: address1, city, country. Province handling: pass either province (text — fuzzy-matched, e.g. "Hồ Chí Minh", "HCM", "TPHCM" all resolve to canonical "TP Hồ Chí Minh") OR province_code (1–63). The tool fills the missing field from the canonical Sapo dataset. For district/ward: pass BOTH text name AND code together (use list_districts / list_wards). NOTE: Sapo write API only accepts the pre-2025 3-tier schema. Post-2025 codes (province_code 2001+, district_code "-1") are rejected pre-flight.

Update an existing customer address. Only provided fields are modified. To set this address as default, use set_default_customer_address (Sapo dedicated endpoint). IMPORTANT: When changing subdivision fields, pass BOTH the text name AND the code (e.g. province + province_code together) — codes alone are silently dropped. Sapo write API only accepts the pre-2025 3-tier schema; new 2-tier addresses cannot be written via this endpoint (returns 422 "Ward is not supported").

Set a customer's default address via Sapo's dedicated endpoint (PUT /customers/{id}/addresses/{addr_id}/default.json). Returns the address now marked default.

List Vietnamese provinces. Default (omit level) = level=3 = pre-2025 63 tỉnh, 3-tier. Use level=2 for post-2025 34 tỉnh, 2-tier (after merger). Province codes differ between schemas: level=3 codes are "1"–"63"; level=2 codes start at "2001". WORKFLOW: For new schema → list_provinces({level:2}) then list_wards({level:2, province_code}). For old schema → list_provinces() → list_districts({province_code}) → list_wards({district_code}). NOTE: Sapo write endpoints (add/update_customer_address) currently accept ONLY level=3 codes; level=2 is read-only as of 2026-05.

List districts (Quận/Huyện) within a province. Only meaningful for level=3 (pre-2025 3-tier schema, default). With level=2 the response is empty because the district level was abolished on 2025-07-01.

List wards (Phường/Xã). For level=3 (default, 3-tier) pass district_code obtained from list_districts. For level=2 (2-tier post-reform) pass province_code obtained from list_provinces({level:2}). Post-reform wards attach directly to province — their district_code is the sentinel "-1".

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 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.

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

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, note_attributes, email, buyer_accepts_marketing. Verified live 2026-05-01. NOTE: The customer link CANNOT be changed via Private App — Sapo silently ignores customer/customer_id fields on update (no error, no effect). Workarounds for tracking customer on a completed order: (a) tag it — tags: "customer:<id>" (searchable via search_orders); (b) set email — email: <customer.email> (Sapo may auto-match in some reports). For a true DB-level link, use the Sapo admin web UI or wait for OAuth Partner App support. Do NOT cancel + recreate via draft_order to "fix" the link — that loses transaction history, refunds, and inventory state.

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.

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 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.

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.

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.

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.