Translations API overview (revision 2026-04-15.pre)

Before you begin

Check out our general API overview before getting started with specific endpoints.

🚧

The Translations API (revision 2026-04-15) is currently in Beta.

All endpoints in this overview require the revision: 2026-04-15.pre header. The GA revision is planned for 2026-07-15. Endpoint paths and request/response shapes may change before GA.

The Translations API lets you manage multilingual content across campaigns, flows, templates, and universal content programmatically. While Klaviyo's Smart Translations feature provides an in-app localization experience, the Translations API gives you a "bring your own translation" path: export source strings, translate them using your own tools or Translation Management System (TMS), and import the results back into Klaviyo.

📘

When calling the Translations API, your authentication key must have the appropriate scopes: translations:read for GET operations, translations:write for POST, PATCH, and DELETE operations.

Use cases

The Translations API supports the following use cases:

• TMS integration: Export source content from Klaviyo, send it to an external TMS (e.g., Smartling, Phrase, Lokalise), and import the translated strings back, without reverse-engineering template HTML.
• Bulk translation management: List all translations across your account, filter by channel or resource type, and audit which resources are localized.
• Translation setup automation: Programmatically enable translations on campaigns, flows, templates, or universal content, setting source locale, target locales, and fallback locale.
• Localized content updates: Update translation settings (add or remove target locales) or import new translated values for existing translations.
• Translation cleanup: Delete translation collections when they are no longer needed.

Supported channels and resources

The Translations API supports the following channel and resource combinations:

📘

WhatsApp templates have additional constraints: translations can only be created, updated, or deleted when the WhatsApp template is in DRAFT status, due to Meta's approval workflow.

Data model

A translation has the following structure:

• id

  A composite identifier, for example campaign-variation::email::01KH00000000000000000000AB.

• attributes

  • source_locale

    The BCP 47 locale code of the original source content (e.g., "en").

  • target_locales

    An array of locale codes that the content is translated into (e.g., ["fr", "es", "de"]). Must contain at least one item.

  • fallback_locale

    The locale used when translated content is unavailable for a target locale at render time (e.g., "en").

  • channel

    The communication channel: email, sms, mobile_push, or whatsapp.

  • metadata

    Optional, channel-specific metadata. null by default. Populated for WhatsApp translations with Meta-specific information such as template approval status.

  • created

    ISO 8601 timestamp of when the translation was created.

  • updated

    ISO 8601 timestamp of when the translation was last modified.

  • values (additional field)

    An array of translatable content blocks with their translations. Only returned when you request additional-fields[translation]=values on a Get Translation request. Not available on the list endpoint. See Export and import translation values for details.

• relationships

  Each translation has exactly one relationship to the Klaviyo resource it belongs to. The relationship key matches the resource type: campaign-variation, flow-message, template, or template-universal-content.

Quick start: export and import workflow

A typical export-translate-import workflow looks like this:

Step 1: Find the translation for your resource.

curl --request GET \
     --url 'https://a.klaviyo.com/api/translations/?filter=equals(related_resource_id,"YOUR_RESOURCE_ID")' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

Step 2: Export the translation values.

curl --request GET \
     --url 'https://a.klaviyo.com/api/translations/campaign-variation::email::01KH00000000AB?additional-fields[translation]=values' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

The response includes the values array with source content and existing translations:

{
   "data": {
      "id": "campaign-variation::email::01KH00000000AB",
      "type": "translation",
      "attributes": {
         "source_locale": "en",
         "target_locales": ["fr", "es"],
         "fallback_locale": "en",
         "channel": "email",
         "metadata": null,
         "created": "2026-03-01T12:00:00+00:00",
         "updated": "2026-03-15T09:30:00+00:00",
         "values": [
            {
               "id": "scheduled_message::01KH00000000AB::subject",
               "source_value": "Spring Sale starts now!",
               "translations": {
                  "fr": "",
                  "es": ""
               }
            },
            {
               "id": "scheduled_message::01KH00000000AB::body",
               "source_value": "Shop our biggest sale of the season.",
               "translations": {
                  "fr": "",
                  "es": ""
               }
            }
         ]
      },
      "relationships": {
         "campaign-variation": {
            "data": {
               "type": "campaign-variation",
               "id": "01KH00000000AB"
            }
         }
      },
      "links": {
         "self": "https://a.klaviyo.com/api/translations/campaign-variation::email::01KH00000000AB"
      }
   }
}

📘

Empty strings ("") in the translations object indicate that a translation has not yet been provided for that locale.

Step 3: Translate the content using your TMS, translation team, or any tool of your choice.

Step 4: Import the translated values by sending a PATCH request with the updated values array. The payload format is symmetric with the export: you can take the exported values, fill in the translations, and send them back.

curl --request PATCH \
     --url 'https://a.klaviyo.com/api/translations/campaign-variation::email::01KH00000000AB' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2026-04-15.pre' \
     --data '{
  "data": {
    "type": "translation",
    "id": "campaign-variation::email::01KH00000000AB",
    "attributes": {
      "values": [
        {
          "id": "scheduled_message::01KH00000000AB::subject",
          "translations": {
            "fr": "Les soldes de printemps commencent maintenant !",
            "es": "Las rebajas de primavera empiezan ahora!"
          }
        },
        {
          "id": "scheduled_message::01KH00000000AB::body",
          "translations": {
            "fr": "Profitez de nos plus grandes promotions de la saison.",
            "es": "Compra en nuestra mayor venta de la temporada."
          }
        }
      ]
    }
  }
}'

📘

Partial imports

Import is a partial update: only the content blocks and locales you include in the values array are updated. Omitted blocks and locales remain unchanged. Re-importing the same translations is safe and idempotent.

🚧

target_locales is a full replacement

Unlike values, the target_locales attribute is not additive. Sending "target_locales": ["it"] replaces the entire list, removing any previously set locales. To add a locale, include all existing locales in the array. For example, if your current targets are ["es", "fr"] and you want to add Italian, send "target_locales": ["es", "fr", "it"].

Note that removing a locale from target_locales does not delete its translation values. If you have translations for ["es", "fr"] and update to ["it"], the es and fr values are retained. Updating back to ["es", "fr", "it"] restores access to all three locales with their existing translations intact.

Create a translation

To enable translations on a resource, send a POST request to Create Translation. You must specify exactly one relationship to identify the resource being translated.

curl --request POST \
     --url 'https://a.klaviyo.com/api/translations/' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2026-04-15.pre' \
     --data '{
  "data": {
    "type": "translation",
    "attributes": {
      "source_locale": "en",
      "target_locales": ["fr", "es"],
      "fallback_locale": "en",
      "channel": "email"
    },
    "relationships": {
      "campaign-variation": {
        "data": {
          "type": "campaign-variation",
          "id": "01KFXS23TVJH0ZWPZW644CRV"
        }
      }
    }
  }
}'

{
   "data": {
      "id": "campaign-variation::email::01KFXS23TVJH0ZWPZW644CRV",
      "type": "translation",
      "attributes": {
         "source_locale": "en",
         "target_locales": ["fr", "es"],
         "fallback_locale": "en",
         "channel": "email",
         "metadata": null,
         "created": "2026-04-15T12:00:00+00:00",
         "updated": "2026-04-15T12:00:00+00:00"
      },
      "relationships": {
         "campaign-variation": {
            "data": {
               "type": "campaign-variation",
               "id": "01KFXS23TVJH0ZWPZW644CRV"
            }
         }
      },
      "links": {
         "self": "https://a.klaviyo.com/api/translations/campaign-variation::email::01KFXS23TVJH0ZWPZW644CRV"
      }
   }
}

🚧

A resource can only have one translation collection. Attempting to create a translation for a resource that already has one returns a 409 Conflict error.

Update translation settings

Use Update Translation to modify translation settings such as adding or removing target locales. All attributes are optional in a PATCH request.

curl --request PATCH \
     --url 'https://a.klaviyo.com/api/translations/campaign-variation::email::01KFXS23TVJH0ZWPZW644CRV' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2026-04-15.pre' \
     --data '{
  "data": {
    "type": "translation",
    "id": "campaign-variation::email::01KFXS23TVJH0ZWPZW644CRV",
    "attributes": {
      "target_locales": ["fr", "es", "de"]
    }
  }
}'

📘

If you change source_locale to a locale that is currently in target_locales, that locale is automatically removed from the target list.

Export and import translation values

Export values

To export translation values, use the additional-fields[translation]=values query parameter on a Get Translation request. This returns the values attribute containing each translatable content block with its source text and current translations.

curl --request GET \
     --url 'https://a.klaviyo.com/api/translations/flow-message::email::01KGABCDEF?additional-fields[translation]=values' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

Each item in the values array has:

• id — The identifier for the translatable content block.
• source_value — The original text in the source locale.
• translations — A map of target locale codes to their translated strings. Empty strings indicate missing translations.

🚧

The additional-fields[translation]=values parameter is only supported on the Get Translation (single resource) endpoint. It is not yet supported on Get Translations (list endpoint) and will return a 400 error if used there.

Import values

To import translations, include a values array in the attributes of a PATCH request to Update Translation. The import format mirrors the export format for payload symmetry: you can export, edit, and re-import with minimal transformation.

Each value object contains:

• id (required) — Must match a valid translatable content block ID from the export.
• source_value (optional) — The original source text. Not required for import, but included in the export response, so you can pass it through as-is.
• translations (required) — A map of locale codes to translated strings. Only the locales you include are updated.

curl --request PATCH \
     --url 'https://a.klaviyo.com/api/translations/flow-message::email::01KGABCDEF' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2026-04-15.pre' \
     --data '{
  "data": {
    "type": "translation",
    "id": "flow-message::email::01KGABCDEF",
    "attributes": {
      "values": [
        {
          "id": "flow_message::01KGABCDEF::subject",
          "translations": {
            "fr": "Bienvenue !",
            "de": "Willkommen!"
          }
        }
      ]
    }
  }
}'

Delete a translation

To remove translations from a resource, use Delete Translation. This removes the translation collection and all associated localized values.

curl --request DELETE \
     --url 'https://a.klaviyo.com/api/translations/campaign-variation::email::01KFXS23TVJH0ZWPZW644CRV' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

A successful deletion returns 204 No Content.

Querying translations

Use the Get Translations list endpoint to find translations across your account. Check out the supported query parameters below:

Filtering examples

Get all email translations:

curl --request GET \
     --url 'https://a.klaviyo.com/api/translations/?filter=equals(channel,"email")' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

Get the translation for a specific resource:

curl --request GET \
     --url 'https://a.klaviyo.com/api/translations/?filter=equals(related_resource_id,"01KFXS23TVJH0ZWPZW644CRV")' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2026-04-15.pre'

Relationship endpoints

Each translation exposes a read-only relationship endpoint for the associated Klaviyo resource:

• GET /api/translations/{id}/campaign-variation/
• GET /api/translations/{id}/flow-message/
• GET /api/translations/{id}/template/
• GET /api/translations/{id}/template-universal-content/

These return the related resource data, useful for navigating from a translation back to the content it belongs to.

Additional resources

• Smart Translations in Klaviyo
• Translations API reference
• Templates API overview
• Universal Content API overview