# Klaviyo

## Update passes from Klaviyo campaigns

> Called by Klaviyo flows to update wallet pass data based on customer segments and marketing automation.\
> \
> \## Authorization\
> Requires \`KlaviyoListener.Write\` scope.\
> \
> \## Klaviyo Integration\
> Configured as a webhook action in Klaviyo flows:\
> 1\. Klaviyo flow triggers (e.g., "Customer entered VIP segment")\
> 2\. Flow sends webhook to this endpoint\
> 3\. Pass is identified by custom identifiers (email, phone, customer ID)\
> 4\. Pass data and metadata are updated\
> 5\. Push notification sent to devices if installed\
> \
> \## Identifiers\
> Flexible identifier matching supports:\
> \- \`email\`: Customer email address\
> \- \`phone\`: Phone number\
> \- \`customerId\`: Internal customer ID\
> \- Any custom identifier configured in pass\
> \
> \## Update Options\
> \- \*\*passType\*\*: Convert pass to different type (e.g., basic → premium)\
> \- \*\*additionalData\*\*: Update custom fields (points, tier, offers)\
> \- \*\*updateMetadata\*\*: Recompute pass visuals (slower, use only when needed)\
> \
> \## Use Cases\
> \- Update loyalty points from campaign\
> \- Add birthday offer to pass\
> \- Upgrade tier based on purchase behavior\
> \- Add personalized coupon codes

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Klaviyo"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"PushUpdateData":{"required":["identifiers"],"type":"object","properties":{"identifiers":{"type":"object","additionalProperties":{"type":"string"},"description":"Identifiers used to locate the target pass (email, phone, customerId, etc.)."},"passType":{"type":["null","string"],"description":"Optional pass type to convert the pass to."},"additionalData":{"type":["null","object"],"additionalProperties":{"type":"null"},"description":"Custom data applied to the pass payload."},"updateMetadata":{"type":"boolean","description":"When true, recomputes pass metadata and visuals.","default":false}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/webhooks/listeners/klaviyo/passes/pushUpdate":{"post":{"tags":["Klaviyo"],"summary":"Update passes from Klaviyo campaigns","description":"Called by Klaviyo flows to update wallet pass data based on customer segments and marketing automation.\n\n## Authorization\nRequires `KlaviyoListener.Write` scope.\n\n## Klaviyo Integration\nConfigured as a webhook action in Klaviyo flows:\n1. Klaviyo flow triggers (e.g., \"Customer entered VIP segment\")\n2. Flow sends webhook to this endpoint\n3. Pass is identified by custom identifiers (email, phone, customer ID)\n4. Pass data and metadata are updated\n5. Push notification sent to devices if installed\n\n## Identifiers\nFlexible identifier matching supports:\n- `email`: Customer email address\n- `phone`: Phone number\n- `customerId`: Internal customer ID\n- Any custom identifier configured in pass\n\n## Update Options\n- **passType**: Convert pass to different type (e.g., basic → premium)\n- **additionalData**: Update custom fields (points, tier, offers)\n- **updateMetadata**: Recompute pass visuals (slower, use only when needed)\n\n## Use Cases\n- Update loyalty points from campaign\n- Add birthday offer to pass\n- Upgrade tier based on purchase behavior\n- Add personalized coupon codes","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Pass identifiers and update payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushUpdateData"}},"text/json":{"schema":{"$ref":"#/components/schemas/PushUpdateData"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PushUpdateData"}}}},"responses":{"200":{"description":"Pass update accepted."},"400":{"description":"Invalid or missing identifiers.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"Unauthorized access to Klaviyo listener.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Unexpected server error."}}}}}}
```

## Synchronize Klaviyo customer profile

> Receives and processes Klaviyo profile update webhooks for email and phone changes.\
> Queues asynchronous tasks to synchronize data back to merchant systems.\
> \
> \## Profile Updates Handled\
> \- Email address changes and subscriptions\
> \- Phone number updates\
> \- Consent and preference changes\
> \- Custom property modifications\
> \
> \## Processing Flow\
> 1\. Receive webhook with profile email and/or phone\
> 2\. Find corresponding customer in local system\
> 3\. Queue background task for synchronization\
> 4\. Task updates customer record and associated passes\
> 5\. Return 202 Accepted with correlation ID\
> \
> \## Authorization\
> Requires \<c>TenantConfigurationAccessControlled\</c> and \<c>ApiThrottling\</c> attributes

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Klaviyo"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"Profile":{"type":"object","properties":{"email":{"type":["null","string"],"description":"Customer email address used for synchronization."},"phone_number":{"type":["null","string"],"description":"Customer phone number used for synchronization."}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/webhooks/listeners/klaviyo/profiles/sync":{"post":{"tags":["Klaviyo"],"summary":"Synchronize Klaviyo customer profile","description":"Receives and processes Klaviyo profile update webhooks for email and phone changes.\nQueues asynchronous tasks to synchronize data back to merchant systems.\n\n## Profile Updates Handled\n- Email address changes and subscriptions\n- Phone number updates\n- Consent and preference changes\n- Custom property modifications\n\n## Processing Flow\n1. Receive webhook with profile email and/or phone\n2. Find corresponding customer in local system\n3. Queue background task for synchronization\n4. Task updates customer record and associated passes\n5. Return 202 Accepted with correlation ID\n\n## Authorization\nRequires <c>TenantConfigurationAccessControlled</c> and <c>ApiThrottling</c> attributes","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Profile object with email and/or phone number for identification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}},"text/json":{"schema":{"$ref":"#/components/schemas/Profile"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"responses":{"200":{"description":"Profile synchronization task scheduled."},"401":{"description":"Unauthorized access to Klaviyo listener.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Unexpected server error."}}}}}}
```