Import Users and Subscriptions

Loads users, their aliases, their attributes and their subscription history into the subscriptions store — the same store the SDK and store webhooks write to, read back by GET /v3/users/{app_user_id}/subscriptions.

Send at most 500 users and 2000 subscriptions per request; a larger batch is rejected with 400 and will fail identically on retry.

Every write is idempotent and merged by the timestamps on the record, so re-posting a batch is safe and a 5xx should be retried with the same body. Subscription status is derived from the lifecycle timestamps you send (refunded_at, billing_issues_detected_at, grace_period_expires_at, unsubscribe_detected_at, expires_at) rather than supplied directly.

A request is applied in three passes — identity, then ownership, then subscription state — and it is NOT all-or-nothing: if a later pass fails, the earlier ones have already been written. This is safe to recover from and needs no cleanup on your side; re-post the same batch and the already-written records are rewritten identically. Do not treat a failed request as though nothing landed, and do not attempt to compensate by deleting.

Send updated_at as the time the store last reported the subscription, not the time of the request: it decides whether an imported row outranks a live store event for the same subscription.

Attributes sent here reach the subscriptions store only — they do not emit analytics events. Use POST /v3/users/{app_user_id}/attributes for attributes that should also reach charts and campaigns.

Rate limited per application: a 429 carries Retry-After. The store is written by a single process that is also handling live subscription events, so imports are paced deliberately.

Requires imports:write scope.