Checkout Functions

Overview

Checkout Functions (v1.7) run in a 50 ms pipeline during every checkout request. Four function types are available:

• discount_calculate — Apply percentage or fixed discounts to orders or line items
• shipping_filter_and_sort — Hide, rename, or reorder shipping rates
• payment_customization — Hide or reorder payment methods
• checkout_validate — Block checkout with a custom error message

Each function runs in rule mode (JSON AST evaluated server-side) or wasm mode (WebAssembly binary sandboxed via wazero).

Quick Start

Create a function via the Admin UI at Marketing → Checkout Functions, or via the API:

POST /admin/functions
{
  "name": "High-Value Order Discount",
  "function_type": "discount_calculate",
  "mode": "rule",
  "enabled": true,
  "rule_config": {
    "conditions": { "all": [{ "field": "cart.subtotal_cents", "operator": "gt", "value": 10000 }] },
    "actions": [{ "type": "percentage_discount", "value": 10, "target": "order" }]
  }
}

Test any function against a simulated cart using POST /admin/functions/:id/test — no live orders are affected.

Rule Engine

Rule-mode functions use a JSON AST. Supported condition fields include: cart.subtotal_cents, cart.item_count, cart.total_weight_grams, customer.tags, customer.email, shipping.country_code, now.hour, now.day_of_week.

Operators: eq, neq, gt, gte, lt, lte, contains, not_contains, in, not_in, starts_with, ends_with.

Aggregates over array fields: SUM, COUNT, MIN, MAX, AVG. Conditions can be nested under all (AND) or any (OR) quantifiers.

Action types

• percentage_discount — value in percent, target: order | line_item
• fixed_discount — value in cents, target: order | line_item
• hide_shipping_rate — hide by handle
• rename_shipping_rate — rename by handle
• sort_shipping_rates — reorder rates
• hide_payment_method — hide by method string
• reorder_payment_methods — reorder methods
• add_error — block checkout with a message

WASM Functions

Upload a WebAssembly binary compiled from any language that targets WASM. The wazero sandbox executes it with a 50 ms timeout, no network, and no filesystem.

1. Create function with "mode": "wasm"
2. Upload binary: POST /admin/functions/:id/upload-wasm (multipart, max 1 MB)
3. Enable: PUT /admin/functions/:id with "enabled": true

Protocol

Cartly sends a JSON payload on stdin; your function writes JSON operations to stdout.

// stdin
{"function_type": "discount_calculate", "cart": {...}}
// stdout
{"operations": [{"type": "percentage_discount", "value": 10, "target": "order"}]}

Magic bytes (\0asm) are validated before execution. Binaries are cached in-memory with a 60 s TTL.

Checkout Branding

Manage at Online Store → Checkout Branding. Settings are injected as CSS custom properties into the checkout page.

• GET /admin/checkout/branding — get current branding
• PUT /admin/checkout/branding — update colors, typography, corner radius
• GET /shops/:shopId/checkout/branding — storefront: returns CSS variables

Fields: primary_color, background_color, text_color, error_color, button_style (pill | rounded | square), corner_radius (px), font_family, font_size_base, custom_css.

Extension Points

Apps inject Remote UI components into 8 named slots:

• after_contact
• after_shipping_address
• after_shipping_methods
• after_payment_methods
• before_order_summary
• after_order_summary
• before_footer
• after_footer

Safe Remote UI components: BlockStack, InlineStack, Text, Heading, TextField, Button, Banner, Divider, Image, Badge.

Register: POST /shops/:shopId/checkout/extensions (OAuth token)
Query: GET /shops/:shopId/checkout/extensions?point=after_contact

API Reference