{
  "openapi": "3.0.2",
  "info": {
    "title": "Klaviyo API",
    "version": "2026-07-15",
    "description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.",
    "contact": {
      "name": "Klaviyo Developer Experience Team",
      "email": "developers@klaviyo.com",
      "url": "https://developers.klaviyo.com"
    },
    "termsOfService": "https://www.klaviyo.com/legal/api-terms",
    "license": {
      "name": "License",
      "url": "https://www.klaviyo.com/legal"
    }
  },
  "servers": [
    {
      "url": "https://a.klaviyo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "Klaviyo-API-Key": []
    }
  ],
  "paths": {
    "/client/subscriptions": {
      "post": {
        "operationId": "create_client_subscription",
        "summary": "Create Client Subscription",
        "description": "Creates a subscription and consent record for email and/or SMS channels based on the provided `email` and `phone_number` attributes, respectively. One of either `email` or `phone_number` must be provided.\n\nThis endpoint is specifically designed to be called from publicly-browseable, client-side environments only and requires a [public API key (site ID)](https://www.klaviyo.com/settings/account/api-keys). Never use a private API key with our client-side endpoints.\n\nDo not use this endpoint from server-side applications.\nTo subscribe profiles from server-side applications, instead use [POST /api/profile-subscription-bulk-create-jobs](https://developers.klaviyo.com/en/reference/subscribe_profiles).\n\nProfiles can be opted into multiple channels: email marketing, SMS marketing, and SMS transactional. You can specify the channel(s) to subscribe the profile to by providing a subscriptions object in the profile attributes.\n\nIf you include a subscriptions object, only channels in that object will be subscribed.  You can use this to update `email` or `phone` on the profile without subscribing them, for example, by setting the profile property but omitting that channel in the subscriptions object. If a subscriptions object is not provided, subscriptions are defaulted to `MARKETING`.<br><br>*Rate limits*:<br>Burst: `350/s`<br>Steady: `750/m`\n\n**Scopes:**\n`subscriptions:write`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/create_client_subscription.json)",
        "parameters": [
          {
            "name": "company_id",
            "in": "query",
            "description": "Your Public API Key / Site ID. See [this article](https://help.klaviyo.com/hc/en-us/articles/115005062267) for more details.",
            "required": true,
            "schema": {
              "description": "Your Public API Key / Site ID. See [this article](https://help.klaviyo.com/hc/en-us/articles/115005062267) for more details.",
              "type": "string",
              "example": "PUBLIC_API_KEY"
            }
          },
          {
            "name": "revision",
            "in": "header",
            "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])",
            "required": true,
            "schema": {
              "type": "string",
              "default": "2026-07-15"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "$ref": "#/components/schemas/OnsiteSubscriptionCreateQuery"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "security": [],
        "tags": [
          "Client"
        ],
        "x-klaviyo-pre-release": "None",
        "x-klaviyo-ratelimit": {
          "burst": "350/s",
          "steady": "750/m"
        },
        "x-klaviyo-scopes": [
          "subscriptions:write"
        ]
      }
    }
  },
  "components": {
    "responses": {
      "ClientError": {
        "description": "Client Error",
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "code",
                      "title",
                      "detail"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "detail": {
                        "type": "string"
                      },
                      "source": {
                        "type": "object",
                        "properties": {
                          "pointer": {
                            "type": "string"
                          },
                          "parameter": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "required": [
                "errors"
              ]
            }
          }
        }
      },
      "ServerError": {
        "description": "Server Error",
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "code",
                      "title",
                      "detail"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "detail": {
                        "type": "string"
                      },
                      "source": {
                        "type": "object",
                        "properties": {
                          "pointer": {
                            "type": "string"
                          },
                          "parameter": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "required": [
                "errors"
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "ClickTrackingSubscriptionParameters": {
        "type": "object",
        "properties": {
          "consent": {
            "description": "The click-tracking consent to grant. Currently supports \"SUBSCRIBED\".",
            "type": "string",
            "example": "SUBSCRIBED",
            "enum": [
              "SUBSCRIBED"
            ]
          }
        },
        "required": [
          "consent"
        ]
      },
      "EmailSubscriptionParameters": {
        "type": "object",
        "properties": {
          "marketing": {
            "description": "The parameters to subscribe to on the \"EMAIL\" Channel. Currently supports \"MARKETING\".",
            "$ref": "#/components/schemas/SubscriptionParameters",
            "nullable": true
          },
          "open_tracking": {
            "description": "The open-tracking consent to grant on the \"EMAIL\" channel. Open-tracking consent is recorded on the profile only; it does not by itself add the profile to a list specified in the request.",
            "$ref": "#/components/schemas/OpenTrackingSubscriptionParameters",
            "nullable": true
          },
          "click_tracking": {
            "description": "The click-tracking consent to grant on the \"EMAIL\" channel. Click-tracking consent is recorded on the profile only; it does not by itself add the profile to a list specified in the request.",
            "$ref": "#/components/schemas/ClickTrackingSubscriptionParameters",
            "nullable": true
          }
        }
      },
      "ListEnum": {
        "type": "string",
        "enum": [
          "list"
        ]
      },
      "OnsiteSubscriptionCreateQuery": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/OnsiteSubscriptionCreateQueryResourceObject"
          }
        },
        "required": [
          "data"
        ]
      },
      "OnsiteSubscriptionCreateQueryResourceObject": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionEnum"
          },
          "attributes": {
            "type": "object",
            "properties": {
              "custom_source": {
                "description": "A custom method detail or source to store on the consent records for this subscription.",
                "type": "string",
                "example": "Homepage footer signup form",
                "nullable": true
              },
              "profile": {
                "type": "object",
                "properties": {
                  "data": {
                    "$ref": "#/components/schemas/ProfileUpsertQueryWithSubscriptionsResourceObject"
                  }
                },
                "required": [
                  "data"
                ]
              }
            },
            "required": [
              "profile"
            ]
          },
          "relationships": {
            "type": "object",
            "properties": {
              "list": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "$ref": "#/components/schemas/ListEnum"
                      },
                      "id": {
                        "description": "The list ID to add the newly subscribed profile to.",
                        "type": "string",
                        "example": "Y6nRLr"
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ]
                  }
                }
              }
            },
            "required": [
              "list"
            ]
          }
        },
        "required": [
          "type",
          "attributes",
          "relationships"
        ]
      },
      "OpenTrackingSubscriptionParameters": {
        "type": "object",
        "properties": {
          "consent": {
            "description": "The open-tracking consent to grant. Currently supports \"SUBSCRIBED\".",
            "type": "string",
            "example": "SUBSCRIBED",
            "enum": [
              "SUBSCRIBED"
            ]
          }
        },
        "required": [
          "consent"
        ]
      },
      "PatchIdentifiers": {
        "type": "object",
        "properties": {
          "append": {
            "type": "object"
          },
          "unappend": {
            "type": "object"
          }
        }
      },
      "ProfileEnum": {
        "type": "string",
        "enum": [
          "profile"
        ]
      },
      "ProfileLocation": {
        "type": "object",
        "properties": {
          "address1": {
            "description": "First line of street address",
            "type": "string",
            "example": "89 E 42nd St",
            "nullable": true
          },
          "address2": {
            "description": "Second line of street address",
            "type": "string",
            "example": "1st floor",
            "nullable": true
          },
          "city": {
            "description": "City name",
            "type": "string",
            "example": "New York",
            "nullable": true
          },
          "country": {
            "description": "Country name",
            "type": "string",
            "example": "United States",
            "nullable": true
          },
          "latitude": {
            "description": "Latitude coordinate. We recommend providing a precision of four decimal places.",
            "example": "40.7128",
            "nullable": true,
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "longitude": {
            "description": "Longitude coordinate. We recommend providing a precision of four decimal places.",
            "example": "74.0060",
            "nullable": true,
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "region": {
            "description": "Region within a country, such as state or province",
            "type": "string",
            "example": "NY",
            "nullable": true
          },
          "zip": {
            "description": "Zip code",
            "type": "string",
            "example": "10017",
            "nullable": true
          },
          "timezone": {
            "description": "Time zone name. We recommend using time zones from the IANA Time Zone Database.",
            "type": "string",
            "example": "America/New_York",
            "nullable": true
          },
          "ip": {
            "description": "IP Address",
            "type": "string",
            "example": "127.0.0.1",
            "nullable": true
          }
        }
      },
      "ProfileMeta": {
        "type": "object",
        "properties": {
          "patch_properties": {
            "description": "Specify one or more patch operations to apply to existing property data",
            "example": {
              "append": {
                "skus": "92538"
              }
            },
            "$ref": "#/components/schemas/ProfileMetaPatchProperties",
            "nullable": true
          },
          "patch_identifiers": {
            "description": "Specify one or more patch operations to apply to existing identifier data. Currently only `email` is supported, and it is used to add or remove secondary email addresses on a profile.",
            "example": {
              "append": {
                "email": [
                  "example@test.com",
                  "another@example.com"
                ]
              }
            },
            "$ref": "#/components/schemas/PatchIdentifiers",
            "nullable": true
          }
        }
      },
      "ProfileMetaPatchProperties": {
        "type": "object",
        "properties": {
          "append": {
            "description": "Append a simple value or values to this property array",
            "type": "object",
            "example": {
              "skus": "92538"
            },
            "nullable": true
          },
          "unappend": {
            "description": "Remove a simple value or values from this property array",
            "type": "object",
            "example": {
              "skus": "40571"
            },
            "nullable": true
          },
          "unset": {
            "description": "Remove a key or keys (and their values) completely from properties",
            "example": "skus",
            "nullable": true,
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        }
      },
      "ProfileUpsertQueryWithSubscriptionsResourceObject": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ProfileEnum"
          },
          "id": {
            "description": "Primary key that uniquely identifies this profile. Generated by Klaviyo.",
            "type": "string",
            "nullable": true
          },
          "attributes": {
            "type": "object",
            "properties": {
              "email": {
                "description": "Individual's email address",
                "type": "string",
                "example": "sarah.mason@klaviyo-demo.com",
                "nullable": true
              },
              "phone_number": {
                "description": "Individual's phone number in E.164 format",
                "type": "string",
                "example": "+15005550006",
                "nullable": true
              },
              "external_id": {
                "description": "A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.",
                "type": "string",
                "nullable": true
              },
              "_kx": {
                "description": "Also known as the `exchange_id`, this is an encrypted identifier used for identifying a\nprofile by Klaviyo's web tracking.\n\nYou can use this field as a filter when retrieving profiles via the Get Profiles endpoint.",
                "type": "string",
                "nullable": true
              },
              "first_name": {
                "description": "Individual's first name",
                "type": "string",
                "example": "Sarah",
                "nullable": true
              },
              "last_name": {
                "description": "Individual's last name",
                "type": "string",
                "example": "Mason",
                "nullable": true
              },
              "organization": {
                "description": "Name of the company or organization within the company for whom the individual works",
                "type": "string",
                "example": "Example Corporation",
                "nullable": true
              },
              "locale": {
                "description": "The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)",
                "type": "string",
                "example": "en-US",
                "nullable": true
              },
              "title": {
                "description": "Individual's job title",
                "type": "string",
                "example": "Regional Manager",
                "nullable": true
              },
              "image": {
                "description": "URL pointing to the location of a profile image",
                "type": "string",
                "example": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg",
                "nullable": true
              },
              "location": {
                "$ref": "#/components/schemas/ProfileLocation",
                "nullable": true
              },
              "properties": {
                "description": "An object containing key/value pairs for any custom properties assigned to this profile",
                "type": "object",
                "example": {
                  "pseudonym": "Dr. Octopus"
                },
                "nullable": true
              },
              "subscriptions": {
                "$ref": "#/components/schemas/SubscriptionChannels",
                "nullable": true
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ProfileMeta",
            "nullable": true
          }
        },
        "required": [
          "type",
          "attributes"
        ]
      },
      "PushSubscriptionParameters": {
        "type": "object",
        "properties": {
          "marketing": {
            "description": "The parameters to subscribe to marketing on the \"Push\" channel.",
            "$ref": "#/components/schemas/SubscriptionParameters"
          },
          "tokens": {
            "description": "A list of push tokens to register for this profile.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushTokenEntry"
            },
            "nullable": true
          },
          "anonymous_id": {
            "description": "An anonymous identifier for push-only profiles with no email/phone.",
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "marketing"
        ]
      },
      "PushTokenDeviceMetadata": {
        "type": "object",
        "properties": {
          "device_id": {
            "description": "Relatively stable ID for the device. Will update on app uninstall and reinstall",
            "type": "string",
            "example": "1234567890",
            "nullable": true
          },
          "klaviyo_sdk": {
            "description": "The name of the SDK used to create the push token.",
            "type": "string",
            "example": "swift",
            "enum": [
              "android",
              "flutter",
              "flutter_community",
              "react_native",
              "swift"
            ],
            "nullable": true
          },
          "sdk_version": {
            "description": "The version of the SDK used to create the push token",
            "type": "string",
            "example": "1.0.0",
            "nullable": true
          },
          "device_model": {
            "description": "The model of the device",
            "type": "string",
            "example": "iPhone12,1",
            "nullable": true
          },
          "os_name": {
            "description": "The name of the operating system on the device.",
            "type": "string",
            "example": "ios",
            "enum": [
              "android",
              "ios",
              "ipados",
              "macos",
              "tvos"
            ],
            "nullable": true
          },
          "os_version": {
            "description": "The version of the operating system on the device",
            "type": "string",
            "example": "14.0",
            "nullable": true
          },
          "manufacturer": {
            "description": "The manufacturer of the device",
            "type": "string",
            "example": "Apple",
            "nullable": true
          },
          "app_name": {
            "description": "The name of the app that created the push token",
            "type": "string",
            "example": "Klaviyo",
            "nullable": true
          },
          "app_version": {
            "description": "The version of the app that created the push token",
            "type": "string",
            "example": "1.0.0",
            "nullable": true
          },
          "app_build": {
            "description": "The build of the app that created the push token",
            "type": "string",
            "example": "1",
            "nullable": true
          },
          "app_id": {
            "description": "The ID of the app that created the push token",
            "type": "string",
            "example": "com.klaviyo.app",
            "nullable": true
          },
          "environment": {
            "description": "The environment in which the push token was created",
            "type": "string",
            "example": "release",
            "enum": [
              "debug",
              "release"
            ],
            "nullable": true
          }
        }
      },
      "PushTokenEntry": {
        "type": "object",
        "properties": {
          "token": {
            "description": "A push token from APNS or FCM.",
            "type": "string",
            "example": "1234567890abcdef"
          },
          "platform": {
            "description": "The platform on which the push token was created. Either \"ios\" or \"android\".",
            "type": "string",
            "enum": [
              "android",
              "ios"
            ]
          },
          "vendor": {
            "description": "The vendor of the push token. Either \"apns\" or \"fcm\".",
            "type": "string",
            "example": "apns",
            "enum": [
              "apns",
              "fcm"
            ]
          },
          "enablement_status": {
            "description": "The enablement status for the push token.",
            "type": "string",
            "example": "AUTHORIZED",
            "enum": [
              "AUTHORIZED",
              "DENIED",
              "NOT_DETERMINED",
              "PROVISIONAL",
              "UNAUTHORIZED"
            ],
            "nullable": true
          },
          "background": {
            "description": "The background state of the push token.",
            "type": "string",
            "example": "AVAILABLE",
            "enum": [
              "AVAILABLE",
              "DENIED",
              "RESTRICTED"
            ],
            "nullable": true
          },
          "device_metadata": {
            "description": "Metadata about the device that created the push token.",
            "$ref": "#/components/schemas/PushTokenDeviceMetadata",
            "nullable": true
          }
        },
        "required": [
          "token",
          "platform",
          "vendor"
        ]
      },
      "SMSSubscriptionParameters": {
        "type": "object",
        "properties": {
          "marketing": {
            "description": "The parameters to subscribe to marketing on the \"SMS\" Channel.",
            "$ref": "#/components/schemas/SubscriptionParameters",
            "nullable": true
          },
          "transactional": {
            "description": "The parameters to subscribe to transactional messaging on the \"SMS\" Channel.",
            "$ref": "#/components/schemas/SubscriptionParameters",
            "nullable": true
          }
        }
      },
      "SubscriptionChannels": {
        "type": "object",
        "properties": {
          "email": {
            "description": "The subscription parameters to subscribe to on the \"EMAIL\" Channel.",
            "$ref": "#/components/schemas/EmailSubscriptionParameters",
            "nullable": true
          },
          "sms": {
            "description": "The subscription parameters to subscribe to on the \"SMS\" Channel.",
            "$ref": "#/components/schemas/SMSSubscriptionParameters",
            "nullable": true
          },
          "whatsapp": {
            "description": "The subscription parameters to subscribe to on the \"WhatsApp\" Channel.",
            "$ref": "#/components/schemas/WhatsAppSubscriptionParameters",
            "nullable": true
          },
          "push": {
            "description": "The subscription parameters to subscribe to on the \"Push\" Channel.",
            "$ref": "#/components/schemas/PushSubscriptionParameters",
            "nullable": true
          }
        }
      },
      "SubscriptionEnum": {
        "type": "string",
        "enum": [
          "subscription"
        ]
      },
      "SubscriptionParameters": {
        "type": "object",
        "properties": {
          "consent": {
            "description": "The Consent status to be set as part of the subscribe call. Currently supports \"SUBSCRIBED\".",
            "type": "string",
            "example": "SUBSCRIBED",
            "enum": [
              "SUBSCRIBED"
            ]
          },
          "consented_at": {
            "description": "The timestamp of when the profile's consent was gathered. This should only be used when syncing over historical consent info to Klaviyo; if the `historical_import` flag is not included, providing any value for this field will raise an error.",
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "consent"
        ]
      },
      "WhatsAppSubscriptionParameters": {
        "type": "object",
        "properties": {
          "marketing": {
            "description": "The parameters to subscribe to marketing on the \"WhatsApp\" Channel.",
            "$ref": "#/components/schemas/SubscriptionParameters",
            "nullable": true
          },
          "transactional": {
            "description": "The parameters to subscribe to transactional messaging on the \"WhatsApp\" Channel.",
            "$ref": "#/components/schemas/SubscriptionParameters",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "Klaviyo-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`<br>For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#authentication",
        "x-default": "Klaviyo-API-Key your-private-api-key"
      }
    }
  },
  "tags": [
    {
      "name": "Client",
      "description": "client"
    }
  ]
}