Tools reference

The Snipcart MCP Server exposes 38 tools organized into 10 categories. This page documents every tool, its parameters, and what it returns.

You don't need to memorize tool names — your AI assistant picks the right tool based on your natural language request. This reference is useful if you want to understand exactly what's available under the hood.

Orders

list_orders

List orders with optional filters. Returns paginated results.

Parameter Type Required Description
status string No Filter by status: InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled
from string No Start date (ISO 8601, e.g. 2026-01-01)
to string No End date (ISO 8601)
limit number No Number of results (default: 20)
offset number No Pagination offset

Returns: Paginated list with order token, status, customer email, total, and item count.

get_order

Get full details for a specific order.

Parameter Type Required Description
token string Yes The order token

Returns: Complete order object including items, customer info, billing/shipping addresses, and payment details.

update_order

Update order status, payment status, tracking information, or addresses.

Parameter Type Required Description
token string Yes The order token
status string No New order status
paymentStatus string No New payment status
trackingNumber string No Shipping tracking number
trackingUrl string No Tracking URL
email string No Customer email
notes string No Internal notes
billingAddress object No Updated billing address
shippingAddress object No Updated shipping address
customFields array No Custom field values
metadata object No Arbitrary metadata

Returns: The updated order object.

get_order_digital_goods

Retrieve download links for digital products in an order.

Parameter Type Required Description
token string Yes The order token

Returns: Array of digital goods with download URLs.

create_order_notification

Send a notification related to an order. Rate limited to 20 calls per 2 minutes per API key.

Parameter Type Required Description
token string Yes The order token
type string Yes Comment, OrderStatusChanged, OrderShipped, TrackingNumber, or Invoice
deliveryMethod string No Email (sends to customer) or None (internal only). Defaults to None.
message string No Notification message body

Returns: The created notification object.

list_order_notifications

List all notifications that have been sent for an order.

Parameter Type Required Description
token string Yes The order token

Returns: Array of notification objects.

Customers

list_customers

List customers with optional filters.

Parameter Type Required Description
status string No Confirmed or Unconfirmed
email string No Filter by email
name string No Filter by name
from string No Start date (ISO 8601)
to string No End date (ISO 8601)
limit number No Number of results
offset number No Pagination offset

Returns: Paginated list with customer ID, email, status, location, and order stats.

get_customer

Get a customer's full profile and statistics.

Parameter Type Required Description
id string Yes The customer ID

Returns: Complete customer object with addresses, statistics, and order history summary.

get_customer_orders

Get all orders placed by a specific customer.

Parameter Type Required Description
id string Yes The customer ID

Returns: Array of order objects.

update_customer

Update a customer's email or addresses.

Parameter Type Required Description
id string Yes The customer ID
email string Yes New email address
billingAddress object No Updated billing address
shippingAddress object No Updated shipping address
cartToken string No Cart token to associate

Returns: The updated customer object.

delete_customer

Permanently delete a customer account. This action is irreversible.

Parameter Type Required Description
id string Yes The customer ID

Returns: Success confirmation.

Products

list_products

List products with optional filters.

Parameter Type Required Description
userDefinedId string No Filter by custom product ID
from string No Start date (ISO 8601)
to string No End date (ISO 8601)
orderBy string No Sort field
limit number No Number of results
offset number No Pagination offset

Returns: Paginated list with product ID, name, price, stock, and variant count.

get_product

Get full product details.

Parameter Type Required Description
id string Yes The product ID

Returns: Complete product object with variants, categories, and descriptions.

update_product_stock

Update stock levels or inventory management settings.

Parameter Type Required Description
id string Yes The product ID
stock number No New stock quantity (for ByProduct management)
allowOutOfStockPurchases boolean No Whether to allow purchases when out of stock
inventoryManagementMethod string No DontTrack, ByProduct, or ByVariant
variants array No Array of variant objects with variation and stock fields

Returns: The updated product object.

archive_product

Soft-delete a product. The product can be restored from the Snipcart dashboard.

Parameter Type Required Description
id string Yes The product ID

Returns: Success confirmation.

Discounts

list_discounts

List all discounts. Rate limited to 10 calls per minute per API key.

Returns: Array of discount objects.

get_discount

Get details for a specific discount.

Parameter Type Required Description
id string Yes The discount ID

Returns: The discount object.

create_discount

Create a new discount. The required fields depend on the trigger and type you choose.

Parameter Type Required Description
name string Yes Display name for the discount
trigger string Yes Code (coupon), Total (cart value), or Product (specific product)
type string Yes FixedAmount, Rate, AlternatePrice, Shipping, FixedAmountOnItems, AmountOnSubscription, or RateOnSubscription
code string Conditional Required when trigger is Code. The coupon code customers enter.
totalToReach number Conditional Required when trigger is Total. Minimum cart value.
itemId string Conditional Required when trigger is Product. The product ID.
amount number Conditional Required for FixedAmount types. Dollar amount off.
rate number Conditional Required for Rate types. Decimal between 0 and 1 (e.g. 0.10 for 10% off).
shippingDescription string Conditional Required for Shipping type.
shippingCost number Conditional Required for Shipping type (set to 0 for free shipping).
maxNumberOfUses number No Limit total uses across all customers
expires string No Expiration date (ISO 8601)

Common examples:

  • 10% off coupon: trigger=Code, code=SUMMER10, type=Rate, rate=0.10
  • $5 off at $50 cart: trigger=Total, totalToReach=50, type=FixedAmount, amount=5
  • Free shipping: trigger=Code, code=FREESHIP, type=Shipping, shippingDescription="Free shipping", shippingCost=0

Returns: The created discount object.

update_discount

Update an existing discount's properties.

Parameter Type Required Description
id string Yes The discount ID
name string No Updated name
code string No Updated coupon code
amount number No Updated amount
rate number No Updated rate
maxNumberOfUses number No Updated usage limit
expires string No Updated expiration date
archived boolean No Set to true to disable

Returns: The updated discount object.

delete_discount

Delete a discount. This will fail if the discount has been used in completed orders.

Parameter Type Required Description
id string Yes The discount ID

Returns: Success confirmation.

Refunds

list_order_refunds

List all refunds for an order.

Parameter Type Required Description
token string Yes The order token

Returns: Array of refund objects.

get_order_refund

Get details for a specific refund.

Parameter Type Required Description
token string Yes The order token
id string Yes The refund ID

Returns: The refund object.

create_order_refund

Create a refund on an order. This action is irreversible. The refund amount cannot exceed the order total.

Parameter Type Required Description
token string Yes The order token
amount number Yes Refund amount in the order's currency
comment string No Reason for the refund
notifyCustomer boolean No Whether to send an email notification
autoRefundTaxes boolean No Whether to automatically refund associated taxes
status string No Partial or Complete

Returns: The created refund object.

Order log items

list_order_log_items

List internal notes and log entries for an order.

Parameter Type Required Description
token string Yes The order token

Returns: Array of log entry objects.

create_order_log_item

Add an internal note to an order. These notes are only visible in the dashboard, not to customers.

Parameter Type Required Description
token string Yes The order token
content string Yes The note content

Returns: The created log entry.

Abandoned carts

list_abandoned_carts

List abandoned carts. Uses continuation token pagination (not offset-based).

Parameter Type Required Description
limit number No Number of results
continuationToken string No Token from a previous response to load the next page
timeRange string No Predefined range (e.g. LastWeek)
minimalValue number No Minimum cart value
email string No Filter by customer email
productId string No Filter by product

Returns: Paginated list with continuation token for loading more results.

get_abandoned_cart

Get full details for an abandoned cart.

Parameter Type Required Description
token string Yes The abandoned cart token

Returns: Complete cart object with items, customer info, and timestamps.

User sessions

get_user_session

Get details for a user session.

Parameter Type Required Description
token string Yes The session token

Returns: Session object with customer and cart information.

Domains

get_domain

Get your store's primary domain configuration.

Returns: Domain configuration object.

update_domain

Update your store's primary domain.

Parameter Type Required Description
domain string Yes The domain (e.g. mystore.com)
protocol string No HTTPS or HTTP (defaults to HTTPS)

Returns: The updated domain object.

list_allowed_domains

List all domains allowed to embed the Snipcart checkout.

Returns: Array of domain objects.

add_allowed_domains

Add domains to the allowed list.

Parameter Type Required Description
domains array Yes Array of domain strings (e.g. ["mystore.com", "staging.mystore.com"])

Returns: Updated list of allowed domains.

remove_allowed_domains

Remove domains from the allowed list.

Parameter Type Required Description
domains array Yes Array of domain strings to remove

Returns: Updated list of allowed domains.

Shipping methods

list_shipping_methods

List all custom shipping methods.

Returns: Array of shipping method objects.

get_shipping_method

Get details for a specific shipping method.

Parameter Type Required Description
id string Yes The shipping method ID (UUID)

Returns: The shipping method object.

create_shipping_method

Create a custom shipping method with weight-based rates.

Parameter Type Required Description
name string Yes Display name
rates array Yes Array of rate objects: { cost, weight: { from, to } }
onOrderTotalAbove number No Only apply when cart total exceeds this value
postalCodeRegex string No Regex to match postal codes
countryCondition array No Array of { countryCode, stateCode } objects
guaranteedEstimatedDelivery string No Estimated delivery time
localizationId string No Localization ID for translations

Example:

{
  "name": "Express Shipping",
  "rates": [
    { "cost": 25.00, "weight": { "from": 0, "to": 5000 } },
    { "cost": 35.00, "weight": { "from": 5001, "to": 10000 } }
  ],
  "countryCondition": [
    { "countryCode": "US" },
    { "countryCode": "CA" }
  ]
}

Returns: The created shipping method object.

Known limitation: The guaranteedEstimatedDelivery field is accepted by the API but may not persist due to a server-side issue. Set delivery time estimates from the Snipcart dashboard as a workaround.

update_shipping_method

Update an existing shipping method. The server fetches the current state and merges your changes.

Parameter Type Required Description
id string Yes The shipping method ID (UUID)
name string No Updated name
rates array No Updated rates
onOrderTotalAbove number No Updated cart total threshold
postalCodeRegex string No Updated postal code regex
countryCondition array No Updated country conditions

Returns: The updated shipping method object.

delete_shipping_method

Delete a shipping method.

Parameter Type Required Description
id string Yes The shipping method ID (UUID)

Returns: Success confirmation.

Next up: Error handling — Understanding errors and rate limits.

Was this article helpful?