Integrate a helpdesk platform

Overview

This resource will help you as you build an integration between a helpdesk or customer experience (CX) platform and Klaviyo. It walks through why support data belongs in Klaviyo, the recommended integration flow, the ticket and satisfaction events to send, the profile properties to sync, the marquee "pause marketing for frustrated customers" use case, and the authentication and certification requirements, with an API quick reference at the end.

Why connect your helpdesk platform to Klaviyo

Support data is the clearest read a brand has on how a customer actually feels right now. Who has an open complaint, who just rated a resolution five stars, who contacts support constantly. The brands that get the most out of it don't leave that data in the ticketing tool. They push it into the platform where they run every other channel. When that platform is Klaviyo and support data lives there natively, you get measurable wins:

• Stop marketing to frustrated customers. The single most-requested support integration behavior: don't send a cheerful promo to someone with an open complaint. This is the marquee use case, detailed below.
• Follow up after resolution. Ticket resolved is a lifecycle moment. Merchants trigger thank-you, win-back, or review-request flows off it, especially valuable after a high-friction fix.
• Branch on satisfaction. A low CSAT routes into an apology and retention flow; a high CSAT routes into an upsell or advocacy flow.
• Segment on support behavior. Lifetime ticket count, last contact channel, and VIP support status are all audiences a merchant can act on once support data is on the profile.
• Stickier merchants. Support-aware messaging is one of the strongest retention signals across the partner program because it protects the customer relationship at its most fragile moments.

Short version: ticket and satisfaction events from your platform into the Klaviyo profile mean the merchant's marketing team can make messaging support-aware from the same place they run every other channel.

The flow

Primarily one-way push, partner to Klaviyo. Support is event-driven. The value is in the state change, ticket opened, resolved, rated, so events are the heart of this integration:

• Event emission for every support moment. Ticket created, ticket resolved, satisfaction responded, ticket reopened. These are the metrics the merchant builds segments and flows against.
• Profile property sync for current support state. Open ticket count, last ticket status, last CSAT score. These power real-time suppression segments (see below), written inline on the event so a single call covers both streams.

Both fire in real time as tickets move through your platform. Each profile is keyed by email first, with phone where the ticket originated from SMS or WhatsApp. Use the merchant's helpdesk customer ID as a stored property, but always identify by email first; external_id is a secondary reference, not a merge key.

Some helpdesk integrations add an optional bidirectional layer, surfacing Klaviyo profile properties and consent in the agent's ticket sidebar, and routing inbound replies to Klaviyo SMS or WhatsApp campaigns into the helpdesk as tickets via the Conversations API. That layer is optional; the core value is writing support events onto the profile.

On initial install, no historical backfill of past tickets is needed. Support is forward-looking. You may backfill current-state properties (open ticket count, VIP flag) for existing contacts through the bulk profile import job so suppression segments work from Day 1.

Events to send

Event names are not prefixed with your platform name. Branded events handle source attribution automatically when events flow through your OAuth token, so the metric name should just describe the action. Use Title Case payload field names ("CSAT Score", "Resolution Time") so they read cleanly in the Klaviyo property picker and template editor.

Ticket and satisfaction events

Be deliberate about what counts as resolved. Fire Ticket Resolved on the state that actually means "done" in your platform, and document it. If your resolved event fires on an intermediate state that later reopens, the auto-resume half of the suppression use case below behaves inconsistently for merchants.

$value guidance: support events do not carry revenue by default. Don't set $value on ticket or satisfaction events. The exception is if a support conversation directly produces a sale (an agent creates an order or applies a discount inside the ticket). Model that as a distinct event with $value set to the order total, the same way the phone platform guide treats a Call Handling Action, rather than attaching revenue to a ticket lifecycle event.

The "pause marketing for frustrated customers" use case

This is the reason most CX platforms integrate at all, so build for it deliberately. It works entirely through a real-time, self-clearing segment:

1. The signal lands on the profile. Every Ticket Created event updates the reviewer's current state, and the {Platform} Open Ticket Count and {Platform} Last Ticket Status properties reflect it in real time.
2. The merchant builds a segment, not a static suppression list, for example "{Platform} Open Ticket Count is greater than 0" or "{Platform} Last CSAT Score is less than 3 in the last 7 days."
3. The segment is used as exclusion logic. The merchant adds it as a campaign suppression condition, or as a skip/exit condition inside a flow. An abandoned-cart flow checks "is not in the Open Support Ticket segment" before sending the next message.
4. The segment self-resolves. When Ticket Resolved fires and Open Ticket Count drops back to 0, the profile falls out of the segment automatically and normal sends resume, with no manual list management.

The critical implementation point: this only works if you fire both the open signal and the corresponding resolved signal reliably. A partner who emits Ticket Created but never a matching Ticket Resolved breaks the auto-resume half, and merchants end up with customers permanently suppressed. The same data also powers the positive inverse: a "delight" segment (five-star CSAT, recently resolved) for upsell and advocacy flows.

Profile properties to sync

Use Title Case property names prefixed with your platform's name. Replace {Platform} below with the literal name of your platform (e.g., "Acme Open Ticket Count"). These give the merchant a current-state view of each customer and are what the suppression segment keys off.

Implementation notes:

• Profile property writes go through Update Profile (PATCH /api/profiles/{id}/), or are written inline on Create Event (POST /api/events/). Inline on the event is the right default, and it's what keeps Open Ticket Count accurate for the suppression segment.
• Pick property names up front and don't rename them. Renames break every segment, flow, and template that references them.
• Keep dates in ISO 8601 (UTC). Klaviyo treats string-typed dates as strings, which silently breaks date-property segmentation.
• Keep Open Ticket Count decrementing on resolve, not just incrementing on create, or the suppression segment never clears.

Auth, scopes, and certification

Build as a public OAuth app. Private API keys are a non-starter for the marketplace. Start with the Create a public OAuth app guide.

Key OAuth specifics for helpdesk integrations:

• PKCE is required on the authorization code exchange (code_verifier must be included).
• Access tokens are short-lived (1 hour). Refresh tokens are long-lived but rotate on every use. Persist the latest refresh token after every refresh call, or you'll lose the integration on the next refresh.
• Tokens are scoped per Klaviyo account. Merchants with multiple Klaviyo accounts (brands, regions, prod and test) install separately for each.

Scopes to request:

• events:write to emit ticket and satisfaction events. This is the core scope.
• profiles:write to write the support state properties to profiles.
• profiles:read only if you match an existing profile before write, or surface Klaviyo profile data and consent in the agent sidebar.
• conversations:read and conversations:write only if you build the optional two-way SMS or WhatsApp support layer via the Conversations API.
• lists:read and segments:read only if agents view or manage list and segment membership from the ticket UI.

Don't over-scope. Unused scopes get flagged in marketplace review. Branded metric badges happen automatically when events flow through the OAuth token. No extra payload field is needed.

Once functional, submit for App Marketplace review under the Support category. Plan for at least one round of feedback. The review covers OAuth, scopes, install and uninstall validation, and that the integration delivers what your listing claims.

API quick reference

Concrete specs for AI coding assistants and engineers grounding on this doc. The narrative above is the why and the flow. This section is the what-to-actually-type.

Headers (required on every request)

Authorization: Bearer <oauth_access_token>
revision: 2026-04-15
Accept: application/json
Content-Type: application/json

Pin the revision header to a specific date when you ship. Check the API versioning guide for the current latest. Without it you'll get a 400.

Event POST body

Send a ticket event and keep the support-state properties current inline. Identify by email first.

POST /api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "Ticket ID": "tkt_44120",
        "Channel": "email",
        "Subject": "Where is my order?",
        "Priority": "high",
        "Team": "support"
      },
      "time": "2026-06-17T14:22:11Z",
      "unique_id": "tkt_44120-created",
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Ticket Created" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "[email protected]",
            "properties": {
              "{Platform} Open Ticket Count": 1,
              "{Platform} Last Ticket Status": "open",
              "{Platform} Last Contact Channel": "email",
              "{Platform} Last Ticket At": "2026-06-17T14:22:11Z"
            }
          }
        }
      }
    }
  }
}

Include time (when the event occurred, ISO 8601) and unique_id (a stable identifier for the event) on every event. A ticket produces several events over its life, so make unique_id unique per occurrence, for example the ticket ID plus the status (tkt_44120-created, tkt_44120-resolved); Klaviyo uses it to deduplicate.

On resolve, fire Ticket Resolved and write {Platform} Open Ticket Count back down (to 0 when no other tickets are open) and {Platform} Last Ticket Status to resolved, so the suppression segment clears.

Retries

• 429: respect the Retry-After header. Otherwise exponential backoff starting at 1s, cap at 60s, max 5 retries.
• 5xx: same backoff.
• 4xx (other than 429): don't retry. Log and surface to the merchant.

Identifier guidance

• Identify by email first; phone where the ticket came from SMS or WhatsApp. These are the fields Klaviyo merges on.
• external_id is NOT a merge key on its own. Pass it alongside email and store the helpdesk customer ID as a profile property for segmentation.
• If a ticket has no customer email (anonymous chat), track it on your side until an email is known; you can't write an event to a profile without an identifier.

Rate limits

Per-account, not per-app. Standard limits handle typical support volume without effort. For install-time backfill of current-state properties across many contacts, use Bulk Import Profiles (POST /api/profile-bulk-import-jobs/). For merchants at unusual scale, request per-endpoint, per-account increases through Klaviyo Support and CSM before launch rather than ramping into 429s in production.

Glossary

• Klaviyo profile: customer record. Keyed by email, phone, or external ID.
• Klaviyo metric: event type. "Ticket Created," "Satisfaction Survey Responded," etc. Created automatically on first event ingest.
• Klaviyo segment: dynamic audience computed from rules. The self-clearing "open ticket" suppression segment is built here.
• Klaviyo flow: automated journey, triggered by a metric or segment membership. Where post-resolution and CSAT-branched follow-ups live.
• CSAT: customer satisfaction score, the rating a customer gives after a ticket is resolved.
• Suppression segment: a segment used to exclude profiles from sends. For helpdesk, the "has an open ticket" audience that pauses marketing.
• Conversations API: the Klaviyo API for two-way SMS and WhatsApp; used only for the optional support-reply layer.

Resources

• Klaviyo Developer Portal. Start here for everything.
• Create a public OAuth app
• Create Event / Update Profile / Bulk Import Profiles
• Conversations API overview (for the optional two-way support layer)
• Klaviyo App Marketplace, Support category. The existing set of helpdesk integrations.
• App Marketplace Review: [email protected]