Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kit.com/llms.txt

Use this file to discover all available pages before exploring further.

Dynamic content block plugins share the same base configuration as standard content block plugins—name, description, icon, request URL, and settings JSON—with several additional required fields that power the personalization and preview experience.
content block insertion menu
content block configuration
All UI components available for standard content blocks—text inputs, color pickers, search inputs, and the rest of the component library—are available for dynamic content blocks as well.

​
Additional configuration fields

​
dynamic

Set to true to mark this plugin as a dynamic content block. This tells Kit to treat the HTML returned by your endpoint as a Liquid template rather than final, static HTML.

​
identifier

A short, unique string that identifies this content block plugin element within your app (used in the Apps Dashboard and for uniqueness across plugin elements). Rules:
  • Lowercase letters, numbers, and underscores only
  • Must be unique within your app
When the block is linked to an automation event plugin (related_plugin_id), Liquid paths use the linked event node’s identifier, not this content block’s identifier: 
automation.{app_identifier}.{event_node_identifier}.{field_name}
For example, if your app identifier is yourapp and the related event node’s identifier is abandoned_checkout, template variables are scoped under automation.yourapp.abandoned_checkout.*. The content block and event node identifiers are often named similarly by convention, but they are configured separately—only the event node’s identifier appears in that middle segment. The automation event plugin that provides subscriber-specific data for this block. In the Kit App Store builder, this is selected from a dropdown listing your app’s automation event plugins. This links your dynamic content block to the workflow step that captures and stores the data.
Your dynamic content block will only render correctly when used in an automation that includes the linked event plugin. The event plugin is responsible for populating the automation context data that your Liquid variables reference.

​
required_data_fields

An array of top-level field names you declare for this block. When the block is linked to an automation event plugin (related_plugin_id is set), Kit requires both required_data_fields and default_values to be present on save—this is builder-side validation so the integration is configured consistently, not a guarantee that Kit checks every field against live automation payloads before each send. For blocks that use only subscriber custom fields (no related_plugin_id), Kit does not apply that same required-field validation on the plugin element. 
["products", "checkout_url", "subtotal", "total"]

​
default_values

Sample data configured in the App Store builder that Kit uses to render a preview of your block in the email editor. Since the editor doesn’t have access to real subscriber data, Kit substitutes these values when rendering the Liquid template for preview display. Your default_values should reflect a realistic example of the data your block will receive at send time: 
{
  "products": [
    {
      "name": "Vintage Wool Sweater",
      "price": "$89.00",
      "quantity": 1,
      "image_url": "https://example.com/images/sweater.jpg",
      "description": "A cozy classic for the cooler months"
    },
    {
      "name": "Canvas Tote Bag",
      "price": "$34.00",
      "quantity": 2,
      "image_url": "https://example.com/images/tote.jpg",
      "description": "Sturdy and stylish everyday carry"
    }
  ],
  "checkout_url": "https://example.com/cart/checkout",
  "subtotal": "$157.00",
  "total": "$157.00",
  "discount_codes": []
}
Make your default values visually representative. Creators will judge how their email will look based on this preview data, so use realistic product names, images, and amounts rather than placeholder text.

​
Request format

When a creator adds your block to an email or adjusts its settings, Kit makes a POST request to your Request URL with the following body: 
{
  "settings": {
    "button_text": "Complete your order",
    "background_color": "#ffffff",
    "title_color": "#000000"
  },
  "styles": {
    "p": { "color": "#333333", "font-family": "Georgia, serif", "font-size": "16px" },
    "h1": { "font-size": "2em", "font-weight": "bold" },
    "h2": { "font-size": "1.5em", "font-weight": "bold" },
    "a": { "color": "#0066cc" },
    "ul": {},
    "ol": {}
  },
  "dynamic": true,
  "context_variable": "abandoned_checkout"
}
When there is no linked automation event plugin, context_variable is omitted.
  • settings — The creator’s current sidebar setting values, same as a standard content block.
  • styles — The surrounding email’s typography styles, keyed by HTML tag (p, h1–h6, a, ul, ol, blockquote). Each value is an object of CSS property/value pairs (e.g. color, font-family, font-size, line-height). Use these to match your block’s output to the email’s design. Tags with no overrides are included as empty objects.
  • dynamic — Always true for dynamic content block requests.
  • context_variable — Present when the block is linked to an automation event plugin. Value is the identifier string of that linked event node (the same value that appears as the middle segment in Liquid: automation.{app_identifier}.{event_node_identifier}.*). Kit does not send merged workflow context or subscriber payloads on this POST—only settings, styles, dynamic, and optionally context_variable. Use context_variable if you need to branch server-side logic between event types; fetch live data from your own systems using settings and your app’s auth model.

​
Response format

Your endpoint should respond with a JSON object. Kit’s response schema requires an html key; other top-level keys are not validated out, but only html is required for success. The html value should be a Liquid template that references automation data using automation.{app_identifier}.{event_node_identifier}.* when linked to an event node: 
{
  "html": "{% if automation.yourapp.abandoned_checkout %}...{% endif %}"
}
On error, return a non-2xx HTTP status. You may include an errors array in the body for debugging or logging: 
{
  "errors": ["No products found"]
}
See liquid templates for guidance on writing the HTML template, including available variables, loops, and email compatibility best practices.

​
Authentication

Dynamic content block plugins use the same OAuth flow as standard plugins. See OAuth authorization for setup details.