Chimes

Send one notification immediately. You can address it directly with a phone number or email address, or point to a saved customer and let Commerce use that customer's phone number or email address.

Rules

• Phone/SMS recipients require exactly one SMS content source: full_message or message_template.
• Email recipients require exactly one email content source: email or message_template.
• Do not mix SMS and email content in one Send Chime request.
• Email content must include subject, text, and from.address. Optional HTML and headers are safety-scanned before delivery.
• Stored templates must match the resolved recipient transport. SMS recipients require an SMS template; email recipients require an email template.
• recipient must use exactly one of two shapes: inline recipient (type plus matching phone.number or email.address) or saved customer (transport plus customer_id).
• recipient cannot include both type and transport.
• Inline recipients cannot include customer_id.

Required attributes

Optional attributes

Email attributes

To send a Chime to a saved customer, pass recipient.customer_id and choose which contact method to use:

{
  "recipient": {
    "customer_id": "cu_abc123def456",
    "transport": "sms"
  },
  "full_message": "Your order has shipped."
}

To send email to an inline address, use recipient.type: "email" and include the top-level email object:

{
  "recipient": {
    "type": "email",
    "email": {
      "address": "[email protected]"
    },
    "name": "Gloria Kesewaa"
  },
  "email": {
    "subject": "Your receipt from YourBrand",
    "text": "Your receipt is ready. View it at https://yourbrand.example/receipts/or_123.",
    "html": "<p>Your receipt is ready. <a href=\"https://yourbrand.example/receipts/or_123\">View receipt</a>.</p>",
    "from": {
      "name": "YourBrand",
      "address": "[email protected]"
    }
  },
  "purpose": "receipt"
}

To send with a stored template, use the generated template ID and keep variables inside the message_template object:

{
  "recipient": {
    "customer_id": "cu_abc123def456",
    "transport": "sms"
  },
  "message_template": {
    "template_id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "variables": {
      "order_number": "OR-12345",
      "tracking_url": "https://track.example.com/OR-12345"
    }
  }
}

The examples below use the saved-customer shape. If you want to address someone directly instead, replace transport and customer_id with type and the matching inline phone or email details.

Retrieve the complete details of a previously sent Chime by its ID. Returns the full Chime object including transmission status and all custom data you attached during creation. Use this endpoint to track message delivery, verify sends during support requests, and reconcile Chimes with your internal systems.

Required attributes

Retrieve a page of Chimes for the authenticated application. Results are sorted by created_at in descending order so page 1 contains the newest activity first.

Optional attributes

You can filter by recipient, customer_id, both, or neither.

The response size is the number of Chimes actually returned in chimes, not the requested page capacity.

Schedule one notification or a batch of notifications for future delivery. Each recipient can either describe an inline phone or email contact, or reference a saved customer.

Rules

• send_after and recipients are required.
• All recipients in one schedule must resolve to the same transport: SMS or email.
• SMS schedules require exactly one SMS content source: full_message or message_template.
• Email schedules require exactly one email content source: email or message_template.
• Do not mix SMS and email content in one schedule.
• Stored templates must match the resolved recipient transport.
• Each recipient must use exactly one of two shapes: inline recipient (type plus matching phone.number or email.address) or saved customer (transport plus customer_id).
• A recipient cannot include both type and transport.
• send_after must be in the future.

Required attributes

Optional attributes

To schedule for saved customers, include recipients with customer_id and transport:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "sms" },
    { "customer_id": "cu_def456ghi789", "transport": "sms" }
  ],
  "full_message": "Reminder: Your appointment starts tomorrow at 10 AM.",
  "send_after": "2025-12-15T10:00:00Z",
  "request_meta": {
    "idempotency_key": "sched_appointment_cu_abc123_2025_12_15"
  }
}

To schedule email for saved customers, set transport: "email" and provide the top-level email object:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "email" },
    { "customer_id": "cu_def456ghi789", "transport": "email" }
  ],
  "email": {
    "subject": "Your subscription renews tomorrow",
    "text": "Your subscription renews tomorrow. Update billing at https://yourbrand.example/billing.",
    "from": {
      "address": "[email protected]"
    }
  },
  "send_after": "2025-12-15T10:00:00Z",
  "purpose": "reminder"
}

To schedule with a stored template, use the same message_template object shape used by Send Chime:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "email" }
  ],
  "message_template": {
    "template_id": "mtpl_emailRenewal123",
    "variables": {
      "customer_name": "Gloria",
      "renewal_date": "2025-12-16"
    }
  },
  "send_after": "2025-12-15T10:00:00Z",
  "purpose": "reminder"
}

The examples below mix both recipient shapes in the same request.

Retrieve a scheduled Chime and check its execution status. Returns the schedule details, IDs of all Chimes created when it executed, and any delivery failures. Use this to track broadcast delivery success, debug failed recipients, or verify cancellation status.

Required attributes

Response attributes

Cancel a pending scheduled Chime before it executes. Prevents message delivery if called before the send_after time. Returns an error if the schedule already executed or was previously canceled. A retry is safe only when it reuses the same Idempotency-Key; a new cancellation request after cancellation returns an error.

Rules

• Only works on pending schedules (not yet executed)
• Cannot cancel after executed_at is set
• Cannot cancel schedules that are already canceled

Required attributes

Send one message immediately to many recipients. Use this for announcements, updates, or any notification that should go out now to a whole audience.

Rules

• recipients is required.
• sender is optional, but providing it is strongly recommended. The API does not apply a default when it is omitted.
• All recipients in one broadcast must resolve to the same transport: SMS or email.
• SMS broadcasts require message_template, either as a raw SMS string or a stored template object.
• Email broadcasts require exactly one email content source: email or a stored message_template object.
• Do not mix SMS and email content in one broadcast.
• Stored templates must match the resolved recipient transport.
• Each recipient must use exactly one of two shapes: inline recipient (type plus matching phone.number or email.address) or saved customer (transport plus customer_id).
• A recipient cannot include both type and transport.
• Each recipient receives an individual Chime.

Required attributes

Optional attributes

For SMS broadcasts, message_template may be a raw SMS string for legacy inline content or an object with template_id and variables for stored templates. For email broadcasts, message_template must be an object; raw string content is SMS-only.

To broadcast to saved customers, include recipients with customer_id and transport:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "email" },
    { "customer_id": "cu_def456ghi789", "transport": "email" }
  ],
  "email": {
    "subject": "Your order has shipped",
    "text": "Your order has shipped. Track it at https://track.shop.example/abc123.",
    "from": {
      "address": "[email protected]"
    }
  },
  "sender": "ShopBrand",
  "request_meta": {
    "idempotency_key": "broadcast_shipping_2025_12_15"
  }
}

To broadcast an email-only campaign, use email recipients and provide the top-level email object:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "email" },
    {
      "type": "email",
      "email": {
        "address": "[email protected]"
      },
      "name": "Backup Contact"
    }
  ],
  "email": {
    "subject": "Your order has shipped",
    "text": "Your order #12345 has shipped. Track it at https://track.shop.example/abc123.",
    "from": {
      "address": "[email protected]"
    }
  },
  "sender": "ShopBrand",
  "purpose": "order_notification"
}

To broadcast with a stored template, pass message_template as an object:

{
  "recipients": [
    { "customer_id": "cu_abc123def456", "transport": "email" },
    { "customer_id": "cu_def456ghi789", "transport": "email" }
  ],
  "message_template": {
    "template_id": "mtpl_emailShipping123",
    "variables": {
      "order_number": "OR-12345",
      "tracking_url": "https://track.shop.example/OR-12345"
    }
  },
  "sender": "ShopBrand",
  "purpose": "order_notification"
}

The examples below mix both recipient shapes in the same request.

Retrieve a broadcast and check its execution status. Returns the broadcast details, IDs of all Chimes created when it executed, and any delivery failures. Use this to track delivery success, debug failed recipients, or verify cancellation status.

Required attributes

Response attributes

Cancel a pending broadcast before it executes. Since broadcasts execute within seconds, cancellation only works if called immediately after creation. Returns an error if the broadcast already executed or was previously canceled. A retry is safe only when it reuses the same Idempotency-Key; a new cancellation request after cancellation returns an error.

Rules

• Only works on pending broadcasts (not yet executed)
• Cannot cancel after executed_at is set
• Cannot cancel broadcasts that are already canceled
• Narrow time window (typically <5 seconds)

Required attributes