Send bespoke subscription messages

Use the Firmhouse GraphQL API to send purpose-specific Liquid messages through your project’s configured customer communication channel.

Use sendSubscriptionNotification when your integration needs to send a message for a specific purpose that is not covered by one of your configured Firmhouse email templates.

For example, you can send delivery instructions after a particular product is ordered, explain the next step after a manual review, or notify one customer about an exception that applies to their subscription. Supply the subject and Liquid template with each request.

Delivery depends on Send emails to customers with in Settings > Email configuration > General:

• Built-in Firmhouse email notifications (default) (email): the subject becomes the email subject and the Liquid template is rendered inside the standard Firmhouse email layout.
• Custom Klaviyo metrics via the old Klaviyo integration (klaviyo): the subject becomes the event name and the Liquid template must render as a JSON event payload. Without the native integration preview, this option is labeled Custom Klaviyo metrics configured in Email configuration.
• Email flows via the new Klaviyo integration (klaviyo_native) or Disable sending emails or custom Klaviyo metrics (disabled): this mutation records the notification but does not deliver an email or Klaviyo event.

For a bespoke event through the new Klaviyo integration, use sendSubscriptionKlaviyoEvent as described below.

Requirements

• A Firmhouse API access token with write access.
• The Firmhouse subscription ID for a subscription in the same project as the access token.
• Built-in Firmhouse email notifications (default) or the old Klaviyo integration selected for delivery. For the old integration, the Klaviyo app must also be enabled and ready to send events.

Send a message

Call sendSubscriptionNotification with the subscription ID, subject, and Liquid template:

mutation SendSubscriptionNotification(
  $subscriptionId: ID!
  $subject: String!
  $template: String!
) {
  sendSubscriptionNotification(input: {
    subscriptionId: $subscriptionId
    subject: $subject
    template: $template
  }) {
    subscription {
      id
    }
    errors {
      attribute
      message
    }
  }
}

For an email project, variables can contain an HTML message with subscription Liquid variables:

{
  "subscriptionId": "123456",
  "subject": "Your delivery needs a little extra attention",
  "template": "<p>Hi {{ subscription.first_name }},</p><p>We will contact you to arrange a suitable delivery time.</p>"
}

Firmhouse validates the subject and Liquid syntax before accepting the message. Always check errors; an empty list means the notification was accepted for processing, not that it was delivered. Delivery depends on the setting described above.

Klaviyo v1 notification payloads

With Custom Klaviyo metrics via the old Klaviyo integration selected (the klaviyo setting), pass a template that renders as JSON instead of HTML:

{
  "subscriptionId": "123456",
  "subject": "Manual review completed",
  "template": "{\"subscription_id\":\"{{ subscription.id }}\",\"result\":\"approved\"}"
}

This example applies only to the old integration’s notification setting. Selecting Email flows via the new Klaviyo integration does not deliver this notification.

Installing the Klaviyo v2 app leaves your email setting unchanged. This mutation does not enable or configure v2 lifecycle events.

Bespoke Klaviyo events, including v2

To send a Klaviyo event independently of the project’s communication channel, use sendSubscriptionKlaviyoEvent with subscriptionId, eventName, and a properties JSON object. Klaviyo must be connected and enabled. See the GraphQL API reference for the mutation contract and Getting started with Klaviyo for separately configured lifecycle events.

Related

• Generate API access tokens
• Liquid documentation
• Email template Liquid variables
• GraphQL API reference