---
title: "Import Users and Subscriptions"
method: POST
path: "/v2/imports/subscriptions"
tags: ["Imports"]
---

# Import Users and Subscriptions

`POST /v2/imports/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.

## Request body

- object
  - `application_id` integer, required — The application these users belong to
  - `import_id` string — a string at most 128 character(s) long
  - `users` object[], required
    - `app_user_id` string, required — a string at least 1 character(s) long
    - `aliases` string[]
    - `attributes` object
    - `subscriptions` object[]
      - `store` 'app-store' | 'play-store' | 'stripe', required
      - `subscription_id` string, required — a string at least 1 character(s) long
      - `transaction_id` string — a string at least 1 character(s) long
      - `product_id` string, required — a string at least 1 character(s) long
      - `product_type` 'autorenewable' | 'nonRenewable' | 'nonConsumable' | 'consumable'
      - `environment` 'live' | 'test'
      - `starts_at` union, required — ISO 8601 string or epoch milliseconds
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `expires_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `renewed_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `original_purchase_date` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `is_auto_renewable` boolean
      - `unsubscribe_detected_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `billing_issues_detected_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `grace_period_expires_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `refunded_at` union
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `offer_type` 'trial' | 'promotional' | 'code', nullable
      - `price` number, nullable
      - `currency` string, nullable
      - `updated_at` union — ISO 8601 string or epoch milliseconds
        - number — Epoch milliseconds
        - string — ISO 8601 timestamp
      - `metadata` Superwall1apiSchema1v21JsonObject — unresolved $ref

## Response `200`

Success

- object
  - `object` 'subscription_import', required
  - `import_id` string, nullable, required
  - `users_received` number, required
  - `subscriptions_received` number, required
  - `applied` number, required
  - `skipped` number, required
  - `outcomes` object, required
  - `skip_reasons` object, required
  - `parked` number, required

## Other responses

- `400` — The request did not match the expected schema
- `401` — No API key was provided in the request
- `403` — The API key does not have permission to perform this action
- `404` — The requested resource was not found
- `429` — Too many requests have been made in a short period
- `500` — An unexpected error occurred on the server
- `502` — The upstream subscriptions service request failed

---

[API](https://skmtc.dev/superwall/apis/superwall-api-v2.md) · [All operations](https://skmtc.dev/superwall/apis/superwall-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superwall/superwall-api-v2/revisions/44900ad77d2c/schema)