Partner API verification A — marketing and messaging partners

0. Summary

Of 18 claims: 6 CONFIRMED, 9 PARTLY, 1 WRONG, 2 UNVERIFIABLE (plus parts of others).

Five findings change roadmap wording or a gate:

  1. Omnisend events have no partner-side dedupe for automation events (claim 8). eventID exists, but the docs say dedupe is "not working on real-time events used for automations". Slice 1 of the delivery worker (3.4) cannot rely on "the deliveryId goes into the partner's dedupe field" for Omnisend. A duplicate Omnisend event can trigger a merchant automation twice.
  2. Omnisend has no Retry-After header and has moved off /v5 (claims 7, 11). The current API is date-versioned (Omnisend-Version: 2026-03-15, base https://api.omnisend.com/api/). Its docs replace the X-Rate-Limit-* headers with a retryAfter body field that only "some endpoints" return. The limit is 400 requests a minute per brand, shared by every integration of that brand. Joy still calls /v5 and reads x-rate-limit-reset.
  3. Attentive: re-subscribing an existing subscriber sends that person an SMS (claim 14). Fix 2.10 ("consented only") is not enough; the bulk sync must also stop calling subscribe for people who are already subscribed.
  4. LINE: the roadmap's duplicate scenario is wrong (claim 17). A 429 means LINE did not accept the message, so retrying a 429 cannot duplicate it. The retry key matters for timeouts, 5xx and Cloud Task re-execution. LINE also documents no Retry-After header, and a 429 can mean the monthly quota is exhausted, which no retry fixes.
  5. Klaviyo: rate-limit scope and the refresh endpoint limit (claims 1, 4). OAuth quota is per account per installed app; private-key shops share one quota with every other private-key integration of that merchant. The token endpoint allows 10 refreshes a minute, and Joy refreshes on every 401 with no lock.

Unverifiable from official docs: Sendlane and PushOwl limits (claim 15), whether Omnisend nonSubscribed downgrades consent (claim 9, the sandbox test in 1.6 stays necessary), whether Postscript external_id dedupes (claim 16), whether Klaviyo refresh tokens rotate (claim 1).


1. Klaviyo

Claim 1 — refresh with a revoked grant returns 400 invalid_grant; do refresh tokens rotate?

Verdict: PARTLY. The 400 invalid_grant half is CONFIRMED. Rotation is UNVERIFIABLE: the docs imply the refresh token is long-lived, but never say whether the refresh response carries a new one.

Docs — https://developers.klaviyo.com/en/docs/set_up_oauth - "If you make a refresh token request to /oauth/token and receive a 400 response with {"error":"invalid_grant"}" … "in the response body, that means your refresh token is invalid." - "You can treat all invalid_grant responses, regardless of the error_description," … "like the application has been uninstalled by the user." - "This refresh token will remain valid until the app is uninstalled by the user." - "If a refresh token is not used after 90 days, it is revoked." - "Every time the refresh token is called, a new access token is issued, but the previous access token is not revoked." - "Refresh token can only be called 10 times per minute maximum." - Authorization-code response field: "This token can be used to request a new access token and refresh token." The page shows no example body for the refresh response.

Joy today (Local) - F/services/klaviyoService.js:707-760: refresh posts grant_type=refresh_token; on 200 it stores only accessToken (:722-728), never a returned refresh_token. - F/services/klaviyoService.js:732: the invalid_grant branch is unreachable because axios throws on a 4xx; the catch at :752-759 logs and returns null. This matches the roadmap. - F/services/klaviyoService.js:333-345: every 401/403 on an OAuth shop triggers a refresh, with no lock and no backoff.

Corrected wording for 2.1 (add to the "What" line):

On a 200 refresh, store refresh_token as well when the response returns one (Klaviyo does not document whether it rotates). Treat only HTTP 400 with error: invalid_grant as a dead grant; a 429 or 5xx from /oauth/token is transient and must never set auth_broken. Serialise refreshes per shop: the token endpoint allows 10 refreshes a minute.

Claim 2 — correct handling is "re-read the stored token, then mark broken, no revoke call"

Verdict: PARTLY. Not revoking is consistent with the docs. The stated reason for the re-read is weaker than the roadmap suggests, and the docs' own recommendation is to disconnect.

Docs — same page - Sample-code comment: "Disconnect the integration on your end since the customer will need to re-authorize". - "The revoke endpoint only accepts refresh tokens." and "Revoking a refresh token revokes the install, so access tokens issued to it stop working within a few minutes,". - Revoke is for the other direction: "This should be done when a user uninstalls your app from your platform."

Reading (Inference) - After invalid_grant the refresh token is already invalid, so a revoke call achieves nothing. Dropping it is correct. - A concurrent refresh by another worker does not invalidate the refresh token ("the previous access token is not revoked", and the refresh token stays valid until uninstall). So the re-read does not protect against a refresh race. It protects against a reconnect that stored a new grant while old work was in flight. Keep the re-read, but compare the stored refreshToken with the one that failed, not the access token. - auth_broken with tokens kept is a product choice. Klaviyo's guidance is "disconnect"; the kept refresh token is useless once invalid_grant is returned. Keeping it is harmless and only helps diagnosis.

Joy today (Local): F/services/klaviyoService.js:732-748 would revoke and null the tokens if it ever ran; F/repositories/integrationsRepository.js:899-933 revokes on the private-key 401 path.

Corrected wording for 2.1:

On invalid_grant, re-read the document; if the stored refresh token differs from the one that just failed (a reconnect happened), retry once with the stored one. Otherwise mark auth_broken. No revoke call (the grant is already invalid at Klaviyo). Recovery is a merchant re-authorisation only; the kept tokens cannot be reused.

Claim 3 — unique_id on the Events API dedupes; scope and window

Verdict: CONFIRMED. Scope is profile plus metric. No time window is documented.

Docs — https://developers.klaviyo.com/en/reference/create_event (revision 2026-10-15) - "If the unique_id is repeated for the same profile and metric, only the first processed event will be recorded." - "If this is not present, this will use the time to the second." … "Using the default, this limits only one event per profile per second." - Limits: "The size of the event payload must not exceed 5 MB," … "each string cannot be larger than 100 KB."; at most 400 properties. Scope events:write. Rate limit burst 350/s, steady 3500/m.

Joy today (Local) - F/services/klaviyoService.js:641: unique_id: uniqueId || uuidv4(). - F/services/integrateKlaviyoService.js:453: eventData?.uniqueId || eventData?.wishlist_event_id || uuidv4(), so most events get a random id and a resend is a new event. - F/services/klaviyoService.js:555: the bulk event path also sends unique_id.

Note for 3.4: the dedupe key is (profile, metric, unique_id). The deliveryId must therefore be fixed before the first attempt and the metric name must not change between attempts (the event prefix from getKlaviyoEventPrefix is part of the metric name).

Claim 4 — rate limits are per account per endpoint with burst and steady windows; Retry-After is present on 429

Verdict: PARTLY. Burst/steady and Retry-After are CONFIRMED. The scope is more specific than the roadmap's "shop, token or endpoint".

Docs — https://developers.klaviyo.com/en/docs/rate_limits_and_error_handling - "All new API endpoints are rate limited on a per-account basis". - "OAuth apps receive their own rate limit quota per installed app instance (i.e., per account per app)" … "while private key integrations share the same rate limit quota per account." - "two distinct windows: burst (1-second window) and steady (1-minute window)." - Tiers: "XS: 1/s burst; 15/m steady", "S: 3/s burst; 60/m steady", "M: 10/s burst; 150/m steady", "L: 75/s burst; 700/m steady", "XL: 350/s burst; 3500/m steady". - On 429: "those headers are replaced with a Retry-After header" … "returns an int indicating the number of seconds before you can start making requests." … "Immediate retries will always receive a 429 error."

Per-endpoint figures read from the reference pages: Create Event 350/s, 3500/m; Bulk Import Profiles 10/s, 150/m; Update Profile 75/s, 750/m.

Joy today (Local) - F/services/klaviyoService.js:323: reads retry-after. :361: Number(retryAfter) + Math.random(); when the header is missing retryAfter is false, so the delay becomes under one second. - F/services/klaviyoService.js:366-380 with F/repositories/integrationRateLimitRepository.js:30-59: one throttle flag per shop, across all endpoints.

Corrected wording for section 5.2 ("admits work per shop at the partner's real limit scope"):

Klaviyo: the quota is per Klaviyo account per installed OAuth app, and separately per endpoint tier. A private-key shop shares its quota with every other private-key integration of that merchant, so Joy's budget there must stay well under the tier. One throttle flag per shop is too coarse: a 429 on bulk import (10/s, 150/m) must not pause events (350/s, 3500/m).

Claim 5 — a bulk profile import API exists and cannot clear a property with null

Verdict: CONFIRMED.

Docs - https://developers.klaviyo.com/en/docs/use_klaviyos_bulk_profile_import_api — "The Bulk Import Profiles API does not support setting fields to null to clear them." … "Only fields explicitly provided with non-null values will be updated." … "To remove a field value from a profile, use the [Update Profile]... endpoint with the field set to null". - https://developers.klaviyo.com/en/reference/bulk_import_profiles — "Accepts up to 10,000 profiles per request." "The maximum allowed payload size is 5MB." "The maximum allowed payload size per-profile is 100KB." Scopes lists:write, profiles:write. - https://developers.klaviyo.com/en/reference/update_profile — "Note that setting a field to null will clear out the field" … "whereas not including a field in your request will leave it unchanged." unset: "Remove a key or keys (and their values) completely from properties".

Joy today (Local): bulk import at F/services/klaviyoService.js:139 and :501; single-profile PATCH at F/services/klaviyoService.js:192; profile import at :207.

Roadmap 2.3 is consistent. One addition: the bulk import needs lists:write as well as profiles:write; a private key without it fails the bulk path while the single-profile path works.

Claim 6 — error shape when the events:write scope is missing

Verdict: CONFIRMED. It is HTTP 403 with code permission_denied, not a 401.

Docs — https://developers.klaviyo.com/en/docs/use_klaviyos_postman_collections - "If you have used an invalid API key, such as a key missing required scopes," … "you might see an error message like the following:" with "status": 403, "code": "permission_denied", "title": "You do not have permission to perform this action.", "detail": "Your API key is missing required scopes: events:write",.

Joy today (Local): F/services/klaviyoService.js:347-351 matches on detail containing Your API key is missing required scopes: events:write, only on the private-key path (!this.accessToken). F/services/integrateKlaviyoService.js:829-830 stores error: 'MISSING_EVENTS_WRITE_SCOPE'.

Gaps the roadmap should name (Inference from the code and the documented shape) - The match is a substring of one English sentence for one scope. Match on status === 403 && code === 'permission_denied' and parse the scope list after the colon, so profiles:write and lists:write also become capability blocks. - F/services/klaviyoService.js:329 treats 401 and 403 the same. For an OAuth shop a 403 scope error triggers a token refresh (:333-345) that can never help. A 403 permission_denied must go to the capability block, never to refresh and never to auth_broken. This supports decision 7 in section 5.3.


2. Omnisend

Background that affects claims 7 to 11 (Docs): the current Omnisend API is date-versioned. https://api-docs.omnisend.com/reference/overview — "The API version is specified via the Omnisend-Version: 2026-03-15 request header instead of the URL path." "Every request must include the version header." Base URL https://api.omnisend.com/api/. Joy calls https://api.omnisend.com/v5 (F/services/integrate/omnisendService.js:9). The quotes below describe version 2026-03-15; whether /v5 behaves identically is not documented.

Claim 7 — 429 numbers and headers for contacts and events

Verdict: PARTLY. The number is confirmed (400 a minute). The headers the roadmap and the code rely on are documented only for v3.

Docs - https://api-docs.omnisend.com/reference/rate-limit-timeouts-errors — "Rate limits are enforced at the API gateway per brand and apply to all endpoints." "The default limit is 400 requests per minute." "Limits use a sliding window: the counter tracks requests over the last minute". "When a rate limit is exceeded the API returns 429 Too Many Requests." "Some endpoints include a retryAfter field (seconds) in the error response." 429 body: {"type": "https://problems.omnisend.com/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429}. No Retry-After or X-Rate-Limit-* header is documented on this page. - https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15 — headers row: v3 "X-Rate-Limit-Limit / -Remaining / -Reset"; v2026-03-15 "Use 429 responses and retryAfter for backoff". - /contacts and /events are not in the per-endpoint table, so the 400 a minute default applies to both, from one shared counter.

Joy today (Local) - F/services/integrate/omnisendService.js:61-70: reads x-rate-limit-reset, falls back to 60 s. - F/services/integrate/syncOmnisendService.js:376-383: reads e.headers, but the error thrown at omnisendService.js:67-80 has no headers property, so this path always uses exponential backoff. - F/services/integrate/syncOmnisendService.js:390-399: sleeps in the handler, then returns undefined.

Corrected wording for section 0 ("a 429 reschedules the Cloud Task after Retry-After") and 3.4:

Omnisend sends no Retry-After header. Read retryAfter (seconds) from the 429 JSON body when present; otherwise back off with jitter. Because the window slides, there is no reset moment. The limit is 400 requests a minute per brand across all endpoints and all integrations of that brand, so Joy shares it with the merchant's other apps and its own events and contacts compete in one budget. Set Joy's per-shop admission well below 400 a minute.

Claim 8 — does the events API accept an idempotency or event id for dedupe?

Verdict: WRONG as the roadmap uses it. The field exists but does not dedupe the events Joy sends.

Docs — https://api-docs.omnisend.com/reference/post_events - eventID: "UUID of the event (v4, v5, v6, v7)." "Along with 'eventTime' used for historical event deduplication (not working on real-time events used for automations)." "If not provided, it will be generated automatically." - Endpoint: "Customer events are used to track customer behavior and trigger automations based on that behavior." Documented responses: 202 "Accepted", 400 "Validation failed", 500 "Internal server error".

Joy today (Local): F/services/integrate/omnisendService.js:173-181 sends eventName, origin: 'Joy', eventTime: new Date().toISOString(), properties, contact. No eventID. eventTime is regenerated on every attempt.

Consequences (Inference) - Section 0 says "the deliveryId goes into the partner's dedupe field". For Omnisend events, which is slice 1 of 3.4, the partner does not dedupe real-time events. A resend after a timeout can fire a merchant automation twice (an email or an SMS). - The response is 202, so acceptance is asynchronous and a timeout is always ambiguous.

Corrected wording for 3.4, slice 1:

Omnisend events have no partner-side dedupe for automation-triggering events. Send eventID (a UUID, with the original eventTime reused on every attempt) for the historical-dedupe case, but do not count on it. Dedupe is Joy-side only: an Omnisend event whose send timed out is ambiguous and goes to quarantine, exactly like an SMS-triggering send (decision 5). "No duplicate deliveryId" in the done-when line measures Joy's attempts, not Omnisend's side effects.

Also for section 5.2: the deliveryId format must be a UUID, because Omnisend (eventID) and LINE (X-Line-Retry-Key) accept only UUIDs.

Claim 9 — does a contact upsert with channels.email.status: 'nonSubscribed' downgrade a subscribed contact?

Verdict: UNVERIFIABLE from docs. The sandbox matrix in 1.6 remains necessary.

Docs — https://api-docs.omnisend.com/reference/post_contacts - "Creates a new contact. If a contact with the provided email identifier already exists, it will be updated instead." "Returns 201 Created for new contacts and 200 OK when an existing contact was updated." - status is described only as "Subscription status," with values subscribed, nonSubscribed, unsubscribed. Nothing says whether a sent status overrides the stored one. - sendWelcomeMessage: "Whether to send a welcome message for this identifier. Defaults to true." It "Takes effect only if the welcome workflow is enabled."

Joy today (Local): F/services/integrate/omnisendService.js:221-231 sends nonSubscribed on every upsert, for email or for SMS when the contact has only a phone.

Additions to the 1.6 matrix (Inference) - The docs' upsert is keyed on the email identifier. For Joy's phone-only contacts (:226-231) the docs do not promise an update; the v5 migration guide says "POST /contacts now only performs an upsert if the email identifier matches an existing contact". Add a phone-only row: does a repeat sync create a duplicate contact or fail? - Add a sendWelcomeMessage column: the default is true. nonSubscribed probably prevents a welcome message, but this is not stated. - Run the matrix on the API version Joy will use after claim 11 is decided, not only on /v5.

Claim 10 — /batches limits

Verdict: CONFIRMED (limits exist and are small).

Docs — https://api-docs.omnisend.com/reference/post_batches - "Each batch operation can include up to 100 actions." Schema: minItems: 1, maxItems: 100. - Endpoints products, contacts, events, categories; methods POST, PUT. - "This endpoint is rate limited to 400 requests per minute."

Joy today (Local): F/services/integrate/omnisendService.js:116-131 posts {endpoint, items, method: 'POST', origin: 'api'}; :136 polls /batches/{id}.

Note for 3.5: 100 items a batch at 400 batch requests a minute is at most 40,000 items a minute in theory, but batch requests draw on the same per-brand counter as every other call. Status polling is also counted. A batch is accepted with a batchID; completion and per-item errors must be read back, which is what 3.5 means by "completion as distinct from submission".

Claim 11 — v3 and v5 deprecation dates

Verdict: UNVERIFIABLE (no first-party date), with one confirmed fact the roadmap ignores.

Docs - https://api-docs.omnisend.com/docs/migrate-from-v5-to-v2026-03-15 exists. It gives no retirement date. Changes: base URL "v5: https://api.omnisend.com/v5/" to "v2026-03-15: https://api.omnisend.com/api/"; "Authorization: Omnisend-API-Key {key}" replaces "X-API-KEY: {key}"; "Omnisend-Version: 2026-03-15 (required on every request)"; "tags field now replaces instead of appends"; "sendWelcomeEmail removed"; "Channel.statusDate | Channel.statusChangedAt". - https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15 — "410 Gone is a new status code, returned when an API version has been retired." No date. - A third-party issue (nopCommerce, September 2026) relays 31 December 2027 as the v3 shutdown. This is a lead, not evidence; no Omnisend page fetched here states it.

Joy today (Local): only /v5 is used (F/services/integrate/omnisendService.js:9); no /v3 call exists in F/.

Wording to add (new line under "Omnisend" in group 2, or in risk 9):

Omnisend has replaced /v5 with a date-versioned API (Omnisend-Version: 2026-03-15) and publishes a v5 migration guide. No v5 retirement date is published. Ask Omnisend partner support for the v5 end date before building the Omnisend adapters, and build the new adapters (3.4 slices 1 and 2, 3.5) against 2026-03-15, so the work is not done twice. A retired version answers 410; the health service must treat 410 as "Joy must upgrade", not as a merchant auth failure.


3. Mailchimp

Claim 12 — 401/403 semantics, the 10-connection limit, batch operations

Verdict: CONFIRMED, with a 403 nuance.

Docs - https://mailchimp.com/developer/marketing/docs/errors/ — 401: "The API key is either invalid or disabled; there will be more information in the "detail"." 403: "Either the user who created the API key no longer has access to the account," … "or their user level doesn't allow access to the endpoint; there will be more information in the "detail"." Also "User Disabled: This account has been deactivated." - Same page, 429: "The Marketing API sets a limit of 10 simultaneously processing requests per user." "The limit is per user, and not per API key or per client." "Requests may time out for you, but still be running on our backend, reducing the available connections." Second 429 cause: "The Marketing API sets a limit of 500 pending batch webhook events per user." - https://mailchimp.com/developer/marketing/api-concepts/oauth-2/ — "Mailchimp access tokens have no expiry, so there is no refresh_token and nothing to rotate on a schedule." "So a token that stops working means the user revoked your access." "Retrying won't help; send them back through the authorization flow instead." - https://mailchimp.com/developer/marketing/guides/run-async-requests-batch-endpoint/ — "Requests to the Marketing API time out at 120 seconds". "at any one time, you can have at most 500 batch requests with a status of pending." "The results of your batch operation are available to download for seven days after you make the request." "Operations in a request are not guaranteed to run in order." "the Batch endpoint does not enforce uniqueness for the optional operation_id".

Joy today (Local) - F/services/integrate/mailchimpService.js:78-93 and :181-197: every error is logged whole and swallowed; no status is classified. - F/services/integrate/mailchimpService.js:159-169: batch start; :171-177: status poll. F/handlers/schedule/syncMailchimpCustomers.js:17-55: 5-minute cron.

Wording to add to 3.6 (Mailchimp slice):

Mailchimp: 401 means the token was revoked (tokens never expire, there is no refresh), so 401 goes straight to auth_broken with no retry. 403 has three meanings (the authorising user lost access, the user's level does not allow the endpoint, the account is deactivated); read title/detail before choosing auth_broken or a capability block. 429 is a concurrency limit, not a rate: 10 simultaneous requests per Mailchimp user, shared with all of that merchant's other integrations, and a request that timed out on Joy's side still holds a slot. Admission for Mailchimp is therefore a concurrency cap per shop (well under 10), not a requests-per-second budget, and there is no Retry-After.

Claim 13 — is there a dedupe key for member updates?

Verdict: PARTLY. There is no idempotency key. The upsert is addressed by the subscriber hash, so repeating the same body is naturally idempotent (Inference; the docs do not use the word).

Docs — https://mailchimp.com/developer/marketing/api/list-members/add-or-update-list-member/ - "Add or update a list member." subscriber_hash: "The MD5 hash of the lowercase version of the list member's email address." status_if_new: "Subscriber's status. This value is required only if the email address is not already present on the list."

Joy today (Local) - F/services/integrate/mailchimpService.js:85-89: setListMember (PUT) by MD5 hash (:329-334). - F/services/integrate/mailchimpService.js:349-356: the batch path uses PATCH, which does not create a missing member.

Notes (Inference) - State-style updates are safe to resend, but ordering is not protected: an older retried update can overwrite a newer one, and batch operations "are not guaranteed to run in order". The delivery worker needs "latest state wins" for Mailchimp, not only a dedupe key. - Consent, outside the listed claims but the same class as 2.10: mailchimpService.js:81-83 sends status_if_new: 'subscribed', or status: 'subscribed' when isConvertSubscriberMailchimp is set, with no marketing-consent check. Every synced customer who is new to the list is added as subscribed. The roadmap has no item for this.


4. Attentive

Verdict: PARTLY. Limits and consent rules are confirmed and stricter than the roadmap assumes. Event dedupe is UNVERIFIABLE.

Docs - https://docs.attentive.com/docs/api-rate-limits — "Your access token allows you to make up to 150 requests per second for most endpoints." "Subscribe: 10 requests per second". "Identity: 10 requests per second". "Unsubscribe: 5 requests per second". "If you exceed the rate limit, you'll receive a 429 response." Headers x-ratelimit-remaining and x-ratelimit-limit. No Retry-After is documented; the guidance is "a retry mechanism with an exponential backoff schedule." - https://docs.attentive.com/reference/addsubscriptions — "A legal disclosure is required when a user is opted-in programmatically." "Requests to opt-in subscribers must either contain a) a sign-up source id or b) both a locale and a subscription type." "By default, if a subscription already exists, it will try and record the attempt to create the subscription again." "For TEXT subscriptions, this will result in a message being sent to the person" … "indicating that they are already subscribed." On singleOptIn: "We strongly recommend maintaining the standard" … "double opt-in flow, as it serves important legal and compliance purposes." - https://docs.attentive.com/reference/postcustomevents — externalEventId: "A unique identifier representing this specific event. A UUID is recommended." No statement on dedupe. occurredAt: "If the timestamp is older than 12 hours, it will not trigger any relevant Journeys." User: "does not need to be actively subscribed to Attentive."

Joy today (Local) - F/services/integrateAttentiveService.js:435-449: the bulk sync calls subscribeCustomer for every synced customer when signUpSourceId is set, with no consent check and unbounded Promise.allSettled concurrency. - F/services/attentiveService.js:126-158: POST /v1/subscriptions. - F/services/attentiveService.js:243-254: custom event with occurredAt: new Date().toISOString() and no externalEventId. - F/services/attentiveService.js:77, 85: reads retry-after; falls back to 60 s when absent, which per the docs is always.

Corrected wording for 2.10:

In the bulk sync, send a subscribe call only for customers with marketing consent and only when the customer is not already subscribed in Attentive: Attentive records every repeat attempt and, for SMS, texts the person that they are already subscribed, so each re-sync would message every existing subscriber. Cap subscribe calls at Attentive's limit of 10 a second per token (today they run unbounded in parallel). Done when: a non-consented customer gets no subscribe call, and a second bulk sync of the same shop sends no subscribe call at all.

Wording to add to 3.4 slice 2 and decision 5:

Attentive: send externalEventId = deliveryId, but treat dedupe as unproven until the contract test shows it. An event delivered more than 12 hours after occurredAt does not trigger a Journey, so the replay-age limit for Attentive events is 12 hours and a late delivery must not rewrite occurredAt to "now" to get around it without a product decision. No Retry-After header exists; back off with jitter.


5. Drip, Sendlane, PushOwl

Claim 15 — rate limits, auth error codes, idempotency

Verdict: Drip CONFIRMED; Sendlane UNVERIFIABLE; PushOwl UNVERIFIABLE.

Drip (Docs — https://developer.drip.com/) - "You can make up to 50 requests per hour for batch endpoints and 3,600 individual requests per hour for other API endpoints." "Each batch request accommodates up to 1,000 records in the payload for a total of 50,000 updates per hour." - 429 example body: "API rate limit exceeded. Please try again in an hour." Headers X-RateLimit-Limit, X-RateLimit-Remaining. No Retry-After documented. - OAuth: "You should only have to do this once, as tokens do not expire." Errors: "401 Unauthorized" for anonymous access, "403 Forbidden" for insufficient permissions. - No idempotency key. Subscriber create-or-update is keyed by email, so a resend of the same state is harmless (Inference).

Joy today (Local): F/services/dripService.js:176-191 batch POST; :223-237 single POST; any failure sets statusConnectedDrip: false at :245 (single update) and :371-378 (bulk).

Roadmap 2.9 is consistent. Two additions: it cites only :371-378, and the same bug is at :245 on the per-customer path, which runs far more often. And the Drip window is hourly: a 429 should defer to the next hour, and 3,600 single calls an hour is one a second, so any mass operation must use the batch endpoint (50 batches an hour).

Sendlane — the official docs are at https://sendlane.stoplight.io/docs/api-documentation/c53add3c8b16f-overview; the page returned HTTP 404 to an automated fetch, and search returned no limit figures. Not verified. Joy today (Local): F/services/EmailMarketing/sendlanceService.js:22 base https://api.sendlane.com/v2, Bearer token at :33; errors are caught and turned into empty results (:36-39).

PushOwl — the partner API is not publicly documented. The public partner article (https://docs.pushowl.com/en/articles/5367959-how-shopify-app-partners-can-integrate-with-pushowl-seamlessly) describes a partner handle, a secret key and a store token, and gives no rate limit, error code or idempotency field. Not verified. Joy today (Local): F/services/pushOwlService.js:45-46 returns res.json() without checking res.status, as the roadmap says.

Wording for 3.11 (when these three get adapters): "Sendlane and PushOwl limits and error codes must be obtained from the partner before sizing the adapter; none is published." For PushOwl, a push notification is a customer-visible send with no documented dedupe, so it belongs under decision 5 with SMS.


6. Postscript

Claim 16 — properties and events APIs, external_id dedupe, rate limit, partner requirements, "never subscribe"

Verdict: PARTLY. The APIs and the rate limit are confirmed. Dedupe by external_id is not documented. One roadmap statement about partner tokens is not supported by the docs.

Docs - Events — https://developers.postscript.io/reference/create-custom-event: POST /api/v2/events, "Send a Custom Event to use in Flows". external_id: "The unique id of the event on your system. This is an optional field." "If a value is not provided, we will create a default id ourselves based on time of event received." Nothing says a repeated external_id is rejected or merged. Response 202 with event_ids; matching is asynchronous. "If no Subscriber is found for the given identifier(s), the event definition will still be captured". type accepts only letters, digits and underscores. - Properties — https://developers.postscript.io/reference/update-subscriber-by-id: PATCH /api/v2/subscribers/{id}, "Updates data for a given subscriber." "Subscribers can have up to 50 custom properties." "If properties is unset or null, it will be ignored." "tags are additive". The only identifier is the subscriber id. - Rate limit — https://developers.postscript.io/docs/rate-limits: "We allow up to 15 requests per second on our endpoints". "If using a partner token and a shop token, then it is 15 requests per second for that partner/shop combination". 429 body {"error_code": 3002, "error_message": "Rate limit exceeded", "success": false}. No Retry-After documented. - Auth — https://developers.postscript.io/reference/authentication and https://developers.postscript.io/docs/api-authentication: "For Shops, you'll just use your API token in the Authorization header." "It does not require you to have a Partner API Token too." Partners: "Be sure to request your partner keys from the Postscript team." (via a PartnerStack form). Partner calls on behalf of a shop add X-Postscript-Shop-Token "with a shop's Private API Key (obtained from the shop)." - Subscribing — https://developers.postscript.io/reference/create-subscriber: "All subscribers added using this endpoint will be required to confirm they have opted in". "You need to pass either a keyword_id or keyword body parameter when adding a subscriber."

Joy today (Local): no Postscript code exists (git grep -il postscript finds only an unrelated demo file). The pattern named in 4.6 is F/services/integrateAttentiveService.js:49-118.

Verdict per sub-claim - Properties and events APIs exist: CONFIRMED. - external_id as the dedupe field: PARTLY. The field exists and is the right place for deliveryId; that Postscript dedupes on it is undocumented. The default "based on time of event received" hints at dedupe but proves nothing. - 15 requests a second per partner and shop, and "two calls each" for a profile update: CONFIRMED. The update is by subscriber id only, so a lookup comes first; 7.5 updates a second is the right ceiling. Events match by phone or email in one call and draw on the same 15. - "Never subscribe": consistent with the docs. The docs do not forbid a partner from creating subscribers, but creation needs a keyword and the person's own confirmation. The properties and events endpoints cannot create a subscriber or change opt-in status, so "existing subscribers only" holds by construction. - "Postscript's API works for most shops only with a partner token" (4.1): UNVERIFIABLE and contradicted in part. The docs say a shop's own key works without a partner token. A plan restriction on shop API keys may exist but is not in the developer docs.

Corrected wording for 4.6 (beta gates) and 4.1:

Pass the logical deliveryId as external_id; whether Postscript dedupes on it is not documented, so the spike must prove it with a repeated external_id on a test shop before the beta, and until then every ambiguous event send is quarantined. Events answer 202 and are matched asynchronously, so "appears once" is checked in Postscript, not from the HTTP answer. Properties cannot be cleared with null (null is ignored) and are capped at 50 per subscriber, shared with the merchant's other apps: keep Joy's set small and send an explicit empty or zero value instead of null. Event type names allow only letters, digits and underscores. No Retry-After header: back off with jitter on error code 3002.

4.1: replace "Postscript's API works for most shops only with a partner token" with "a partner key (requested from Postscript through its PartnerStack form) lets Joy call on behalf of shops with one app-level credential plus each shop's private key; confirm with Postscript whether shops on every plan can issue an API key".


7. LINE Messaging API

Claim 17 — X-Line-Retry-Key: UUID, 24-hour window, 409 on duplicate

Verdict: CONFIRMED. The roadmap's description of when a duplicate happens is wrong.

Docs - https://developers.line.biz/en/docs/messaging-api/retrying-api-request/ — "The retry key shall be a hexadecimal UUID generated by a method of your choice." "A retry key is valid for 24 hours after the first request." "If you retry an API request that the LINE Platform returned the status code 2xx, you'll get the status code 409." (with x-line-accepted-request-id). "API requests without X-Line-Retry-Key can never be retried." By status: 500 and timeout — retry, "Your next request may be successful."; 409 — "Don't retry. The retried request is already accepted."; 4xx — "Don't retry. Retries don't change the result." "A retry with a retry key is counted as one API request, so frequent retries may cause the API rate limit to be reached." A key on an unsupported endpoint is rejected with 400. - https://developers.line.biz/en/reference/messaging-api/ — push message limit "2,000 requests per second."; "The Messaging API applies rate limits to each API function (endpoint) on a per-channel basis." 429 causes: "Exceeded the rate limit for this endpoint." "A large number of messages were sent to the same user." "Exceeded the target limit for sending messages this month." Response headers documented: X-Line-Request-Id and X-Line-Accepted-Request-Id only. No Retry-After.

Joy today (Local) - F/services/line/lineApiService.js:157-177: no X-Line-Retry-Key; on 429 it reads retry-after and defaults to 60 s (so it is always 60 s); every other failure, including 500, returns reason: 'failed' and is not retried. - F/helpers/lineTaskQueue.js:6, 21-40 and F/handlers/schedule/enqueueHandler.js:503-530: only the 429 path re-enqueues, up to 3 times.

Why the roadmap line in 3.2 is wrong (Inference from the docs): "a 429 is retried … with no idempotency key, so a retry can send the same message twice". A 429 means LINE did not accept the request, so retrying it cannot duplicate. A duplicate comes from a timeout or a 500 after LINE accepted the message, or from Cloud Tasks running one task twice. Joy does not retry those today, so today's risk is loss on 5xx and timeout, plus a double execution of a task, not a duplicate from 429.

Corrected wording for section 3.2 (LINE bullet) and for the LINE adapter:

LINE: a 5xx or a timeout is not retried, so the message is lost; a 429 is retried up to 3 times at a fixed 60 seconds (LINE sends no Retry-After). No X-Line-Retry-Key is sent, so a Cloud Task that runs twice sends the message twice.

Adapter rule: send X-Line-Retry-Key = deliveryId (it must be a UUID), identical on every attempt of the same message and recipient. Retry only on 5xx and timeout, within 24 hours of the first attempt. Treat 409 as success. Do not blind-retry 4xx. For 429, read the error message: a rate-limit 429 may be retried with backoff, a monthly-quota or per-user 429 is terminal until the quota changes and should surface in health as a capability block.


8. Intercom

Claim 18 — rate limits, 401 handling

Verdict: CONFIRMED. Joy's handling matches the docs.

Docs - https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting — "Public apps have a default rate limit of 10,000 API calls per minute for each app" … "and 25,000 API calls per minute per workspace." "we evenly distribute this into 10 second windows." X-RateLimit-Reset: "Time when the current 10-second window ends and the number of requests will be reset to the maximum limit." "Shown as UNIX timestamp". "we respond with '429 Too Many Requests' and the error code rate_limit_exceeded". "Not every 429 response includes these headers, so make sure your code can also handle a 429 without them." - https://developers.intercom.com/docs/references/rest-api/errors/http-responses — 401: "Unauthorized -- The API Key was not authorised (or no API Key was found)." 403: "If the API or feature is not available on your current plan or workspace, the error code is api_plan_restricted."

Joy today (Local) - F/services/intercomService.js:142-150: reads x-ratelimit-reset as Unix seconds, 30 s fallback when missing. Correct. - F/services/intercomService.js:106-121: 401 on OAuth tries a refresh; otherwise sets isConnected: false with an error and keeps the tokens. - F/services/intercomService.js:124-129: 400, 404 and 422 are per-record skips.

Notes (Inference) - The 25,000 a minute workspace cap is shared with the merchant's other apps, and X-RateLimit-Remaining "is 0 once either your app's limit or your workspace's limit is reached", so Joy can be throttled by another app's traffic. - 403 api_plan_restricted is a capability block, not auth_broken. Today a 403 falls to the generic throw at :137-140. - When Intercom moves to the health service, its 401 path should set auth_broken instead of isConnected: false (writer 5 in section 2.1).


9. Partner constraints the roadmap ignores

Ordered by how much they can break a fix.

  1. Retry-After is not universal. Section 0 and 5.2 describe one rule: "a 429 reschedules the Cloud Task after Retry-After". Only Klaviyo documents that header. Omnisend (body field retryAfter, some endpoints), Attentive (x-ratelimit-*), Intercom (X-RateLimit-Reset, Unix time, sometimes absent), Drip (hourly window), Postscript, LINE and Mailchimp (concurrency) do not. The worker needs a per-adapter "when may I retry" function and a jittered default.
  2. Partner-side dedupe exists for only some partners. Documented: Klaviyo unique_id (per profile and metric), LINE X-Line-Retry-Key (24 hours). Field exists, dedupe undocumented: Postscript external_id, Attentive externalEventId. Documented as not working for automations: Omnisend eventID. None: Mailchimp, Drip, Intercom, Sendlane, PushOwl. "Passes the logical deliveryId into the partner's dedupe field" is true for two partners; for the rest an ambiguous send must be quarantined or be a safe-to-repeat state update.
  3. deliveryId must be a UUID. Omnisend and LINE accept only UUIDs.
  4. Quota is often shared with the merchant's other apps. Omnisend: per brand across all integrations. Mailchimp: 10 concurrent requests per user. Klaviyo private keys: one quota per account. Intercom: 25,000 a minute per workspace. Admission "at the partner's real limit" would starve or be starved; budgets must sit well below the published limit.
  5. Mailchimp limits concurrency, not rate, and a request that timed out still holds a slot. A queue-level rate limit does not model this.
  6. Omnisend has left /v5. New adapters built on /v5 would be rewritten. See claim 11.
  7. Attentive subscribe has a side effect on existing subscribers (an SMS). See claim 14.
  8. Events expire. Attentive ignores events older than 12 hours for Journeys; LINE retry keys last 24 hours; Klaviyo refresh tokens die after 90 unused days. Decision 5 (maximum replay age) needs a per-partner value, and "retried until delivered" in section 0 is bounded by these.
  9. Klaviyo's token endpoint allows 10 refreshes a minute. The health service's refresh fence must also be a rate fence, and a 429 from the token endpoint must not be read as a dead grant.
  10. 403 is not 401. Klaviyo permission_denied (missing scope), Mailchimp 403 (user level), Intercom api_plan_restricted are capability or plan blocks. Joy treats Klaviyo 401 and 403 alike (F/services/klaviyoService.js:329).
  11. A retired API version answers 410 (Omnisend). Health must classify it as a Joy-side upgrade, not a merchant problem. Klaviyo revisions retire after two years (F/services/klaviyoService.js:26-29 already tracks this).
  12. Mailchimp batch operations are unordered and operation_id is not unique-enforced; 500 pending batches per user is a hard cap. Relevant to 2.5 and to any Mailchimp bulk adapter.
  13. Asynchronous acceptance. Omnisend events and Postscript events answer 202; Klaviyo bulk import and Omnisend batches return a job id. A 2xx is "accepted", not "delivered"; the outcome log (3.1) should record it that way.
  14. Payload limits. Klaviyo event 5 MB, 100 KB a string, 400 properties; bulk import 10,000 profiles, 5 MB, 100 KB a profile. Omnisend batch 100 items. Drip batch 1,000 subscribers. Postscript 50 properties a subscriber. Attentive 200 keys an event type. The worker's "one size limit applies at enqueue" (3.4) should be per adapter.

10. Evidence gaps

11. Unresolved questions

  1. Omnisend: when does /v5 retire, and should the delivery-worker slice 1 target 2026-03-15 from the start?
  2. Omnisend events: given no partner-side dedupe for automations, does decision 5 (ambiguous sends) now also cover Omnisend events in Wave 1, not only SMS in Wave 2?
  3. Attentive: is there an approved way to learn a customer's subscription state before calling subscribe, or should the bulk sync stop subscribing altogether?
  4. Mailchimp: is the unconditional status_if_new: 'subscribed' intended? It is outside this task's claim list but is the same consent class as 2.10.