App Store Connect Configurations V25

App User Erasures V24

Application Webapp Origins V23

Assets V26

Audit Logs V22

Campaigns V234

Chart Annotations5

Charts V28

CLI Agent V22

Custom Store Events1

Custom Stores8

Demand Score V23

Entitlements V28

Events V24

Google Play V28

Grants V21

Imports1

post/v2/imports/subscriptionsImport Users and Subscriptions

Integration Event Names (Service)1

Me V25

Notifications1

Onboarding V21

Organization Access V211

Organizations V22

Paywall Resolver (Public)2

Paywall Templates (Public)1

Paywalls V217

Products V211

Project Auth V26

Project Transfers V27

Projects V224

Query V22

Retention Configurations V212

Retention Default Messages V29

Retention Messages V211

Retention Messaging Onboarding V28

retentionCampaignsV29

RevenueCat V1 (compatible)1

RevenueCat V2 (compatible)4

Stripe Customer Links V21

Surveys V212

Users V214

Users V34

Web2App Integrations V25

Webhooks V212

WorkOS Organization Admin1

Imports

Import Users and Subscriptions

Changed on Oct 29, 2026

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.

post/v2/imports/subscriptions

Request

Base URL
https://api.superwall.com
URL
https://api.superwall.com/v2/imports/subscriptions
Auth
- HTTP bearer
- or API key in cookie accounts_superwall_token
- or HTTP bearer

Request body

application_idinteger required

The application these users belong to

import_idstring

Response

Success

object'subscription_import' required

import_idstring nullable required

users_receivednumber required

subscriptions_receivednumber required

appliednumber required

skippednumber required

outcomesobject required

skip_reasonsobject required

parkednumber required

Changes

Oct 29, 2026778a11cd2c15 Revision changes
- warning
  added the new credentials_missing enum value to the / response property for the response status
- warning
  added the new credentials_missing enum value to the / response property for the response status
- warning
  added the new credentials_missing enum value to the / response property for the response status
- warning
  added the new credentials_missing enum value to the / response property for the response status
- warning
  added the new credentials_missing enum value to the / response property for the response status
- info
  added subschema #1 subschema #2 to the response body anyOf list for the response status
- info
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the response body anyOf list for the response status
- info
  removed subschema #1 subschema #2 from the response body anyOf list for the response status
- info
  removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 from the response body anyOf list for the response status
Sep 9, 2026217c96dc9a29 Revision changes
- breaking
  the request property type changed from string to no type
- breaking
  the // request property type changed from array to no type
- breaking
  the // request property type changed from object to no type
- breaking
  the // request property type changed from array to no type
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from number to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from number to no type for status
- info
  added subschema #1 to the request property anyOf list
- info
  added subschema #1 to the // request property anyOf list
- info
  added subschema #1 to the // request property anyOf list
- info
  added subschema #1 to the // request property anyOf list
- info
  the request property's minLength was decreased from 1 to 0
- info
  added subschema #1 subschema #2 to the response body anyOf list for the response status
- info
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the response body anyOf list for the response status
- info
  added subschema #2 to the response body anyOf list for the response status
- info
  removed subschema #1: Internal Server Error subschema #2: Database Query Error from the response body anyOf list for the response status
- info
  removed subschema #1: Missing API Key subschema #2: Invalid API Key Format subschema #3: Invalid API Key subschema #4: Authentication Failed subschema #5: Invalid Session from the response body anyOf list for the response status
- info
  removed subschema #2: Bad Request from the response body anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  added subschema #1 to the response property anyOf list for the response status
- info
  removed the api_error enum value from the response property for the response status
- info
  removed the api_error enum value from the response property for the response status
- info
  removed the api_error enum value from the response property for the response status
- info
  removed the api_error enum value from the response property for the response status
- info
  removed the authentication_error enum value from the response property for the response status
- info
  removed the authentication_error enum value from the response property for the response status
- info
  removed the authentication_error enum value from the response property for the response status
- info
  removed the authentication_error enum value from the response property for the response status
- info
  removed the authentication_failed enum value from the response property for the response status
- info
  removed the authentication_failed enum value from the response property for the response status
- info
  removed the authentication_failed enum value from the response property for the response status
- info
  removed the authentication_failed enum value from the response property for the response status
- info
  removed the idempotency_key_in_use enum value from the response property for the response status
- info
  removed the idempotency_key_in_use enum value from the response property for the response status
- info
  removed the idempotency_key_in_use enum value from the response property for the response status
- info
  removed the idempotency_key_in_use enum value from the response property for the response status
- info
  removed the insufficient_permissions enum value from the response property for the response status
- info
  removed the insufficient_permissions enum value from the response property for the response status
- info
  removed the insufficient_permissions enum value from the response property for the response status
- info
  removed the insufficient_permissions enum value from the response property for the response status
- info
  removed the internal_error enum value from the response property for the response status
- info
  removed the internal_error enum value from the response property for the response status
- info
  removed the internal_error enum value from the response property for the response status
- info
  removed the internal_error enum value from the response property for the response status
- info
  removed the invalid_api_key enum value from the response property for the response status
- info
  removed the invalid_api_key enum value from the response property for the response status
- info
  removed the invalid_api_key enum value from the response property for the response status
- info
  removed the invalid_api_key enum value from the response property for the response status
- info
  removed the invalid_api_key_format enum value from the response property for the response status
- info
  removed the invalid_api_key_format enum value from the response property for the response status
- info
  removed the invalid_api_key_format enum value from the response property for the response status
- info
  removed the invalid_api_key_format enum value from the response property for the response status
- info
  removed the invalid_reference enum value from the response property for the response status
- info
  removed the invalid_reference enum value from the response property for the response status
- info
  removed the invalid_reference enum value from the response property for the response status
- info
  removed the invalid_reference enum value from the response property for the response status
- info
  removed the invalid_request_error enum value from the response property for the response status
- info
  removed the invalid_request_error enum value from the response property for the response status
- info
  removed the invalid_request_error enum value from the response property for the response status
- info
  removed the invalid_request_error enum value from the response property for the response status
- info
  removed the invalid_session enum value from the response property for the response status
- info
  removed the invalid_session enum value from the response property for the response status
- info
  removed the invalid_session enum value from the response property for the response status
- info
  removed the invalid_session enum value from the response property for the response status
- info
  removed the missing_api_key enum value from the response property for the response status
- info
  removed the missing_api_key enum value from the response property for the response status
- info
  removed the missing_api_key enum value from the response property for the response status
- info
  removed the missing_api_key enum value from the response property for the response status
- info
  removed the organization_required enum value from the response property for the response status
- info
  removed the organization_required enum value from the response property for the response status
- info
  removed the organization_required enum value from the response property for the response status
- info
  removed the organization_required enum value from the response property for the response status
- info
  removed the parameter_invalid enum value from the response property for the response status
- info
  removed the parameter_invalid enum value from the response property for the response status
- info
  removed the parameter_invalid enum value from the response property for the response status
- info
  removed the parameter_invalid enum value from the response property for the response status
- info
  removed the parameter_missing enum value from the response property for the response status
- info
  removed the parameter_missing enum value from the response property for the response status
- info
  removed the parameter_missing enum value from the response property for the response status
- info
  removed the parameter_missing enum value from the response property for the response status
- info
  removed the parameter_unknown enum value from the response property for the response status
- info
  removed the parameter_unknown enum value from the response property for the response status
- info
  removed the parameter_unknown enum value from the response property for the response status
- info
  removed the parameter_unknown enum value from the response property for the response status
- info
  removed the permission_error enum value from the response property for the response status
- info
  removed the permission_error enum value from the response property for the response status
- info
  removed the permission_error enum value from the response property for the response status
- info
  removed the permission_error enum value from the response property for the response status
- info
  removed the rate_limit_error enum value from the response property for the response status
- info
  removed the rate_limit_error enum value from the response property for the response status
- info
  removed the rate_limit_error enum value from the response property for the response status
- info
  removed the rate_limit_error enum value from the response property for the response status
- info
  removed the rate_limit_exceeded enum value from the response property for the response status
- info
  removed the rate_limit_exceeded enum value from the response property for the response status
- info
  removed the rate_limit_exceeded enum value from the response property for the response status
- info
  removed the rate_limit_exceeded enum value from the response property for the response status
- info
  removed the resource_already_exists enum value from the response property for the response status
- info
  removed the resource_already_exists enum value from the response property for the response status
- info
  removed the resource_already_exists enum value from the response property for the response status
- info
  removed the resource_already_exists enum value from the response property for the response status
- info
  removed the resource_archived enum value from the response property for the response status
- info
  removed the resource_archived enum value from the response property for the response status
- info
  removed the resource_archived enum value from the response property for the response status
- info
  removed the resource_archived enum value from the response property for the response status
- info
  removed the resource_missing enum value from the response property for the response status
- info
  removed the resource_missing enum value from the response property for the response status
- info
  removed the resource_missing enum value from the response property for the response status
- info
  removed the resource_missing enum value from the response property for the response status
- info
  removed the side_effect_failed enum value from the response property for the response status
- info
  removed the side_effect_failed enum value from the response property for the response status
- info
  removed the side_effect_failed enum value from the response property for the response status
- info
  removed the side_effect_failed enum value from the response property for the response status
- info
  removed the unsupported_operation enum value from the response property for the response status
- info
  removed the unsupported_operation enum value from the response property for the response status
- info
  removed the unsupported_operation enum value from the response property for the response status
- info
  removed the unsupported_operation enum value from the response property for the response status
- info
  removed the upstream_service_error enum value from the response property for the response status
- info
  removed the upstream_service_error enum value from the response property for the response status
- info
  removed the upstream_service_error enum value from the response property for the response status
- info
  removed the upstream_service_error enum value from the response property for the response status
This list may be incomplete.

Operation history

Import Users and Subscriptions

Request

Request body

Response 200OK

Changes

Response