Data migration guide

Documentation Index

Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

1. Quick orientation

✅ Tip: Download the latest template right before filling it out. Templates change as UniBee evolves—using an old file is the #1 cause of import errors.

​

2. First things first

1. Download UniBee’s Excel templates – In UniBee Admin Portal, open any data list with a ⋯ → Import button (for example, User Management → User List). Click Download template to grab the latest Excel file. All imports use these .xlsx templates; they already include required columns and guidance.
2. Minimal viable import – For teams that just need to bring existing customers online quickly:
   • Create the plans you need (manually in Product & Plan or via the Plan APIs).
   • Configure your payment gateways in UniBee (Settings → Payments).
   • Import Active Subscriptions. The import job auto-creates any missing users, so once the subscriptions are in place, the system is ready for use.
3. When you need more control – Move on to importing users and plans explicitly (details below) before adding subscriptions. This is helpful when you need precise external IDs, custom metadata, or audit requirements.
4. Backup & permissions – Make sure you can see the ⋯ → Import menu (Billing Admin or higher) and export the existing dataset before importing to preserve a rollback point.

​

3. Import playbook

​

3.1 Templates & entry points

Plan imports currently have no UI. If you need to bulk-create plans, call the Plan APIs directly (for example, POST /merchant/plan/create). Imported plans land in Edit status, so you can review them before activating.

​

3.1 User import

• After import: Users are created in ACTIVE status. Existing users can only be overwritten if they were previously imported by the same admin (UniBee tags each record with ImportBy<memberId> to enforce this). No webhook fires; check Activity Logs for ImportNew / ImportOverride.

​

3.2 Plan import (API workflow)

• How it works: There is no “Import plan” button in the UI today. Use the Plan APIs (/merchant/plan/create, /merchant/plan/edit, etc.) to bulk-create plans based on the Excel template. For example:

curl --location --request POST "https://api.unibee.dev/merchant/plan/create" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "productId": 123,
    "planName": "Pro Plan",
    "internalName": "pro_plan_internal",
    "externalPlanId": "legacy-plan-001",
    "amount": 9900,
    "currency": "USD",
    "intervalUnit": "month",
    "intervalCount": 1
  }'

• Key fields: ExternalPlanId, PlanName, InternalName, ProductName, PlanType, PlanAmount, Currency, IntervalUnit, IntervalCount, plus optional Metadata and trial settings.
• After import: Plans stay in Edit status until you review and activate them. This lets you double-check pricing and descriptions before customers see them. Duplicates update descriptive/trial fields. No webhook fires; audit via Activity Logs.

​

3.3 Active subscription import

​

UI workflow

1. Go to Subscription → Subscription List.
2. Click the Import button in the top-right corner and choose Import active subscription.
3. Download the Excel template if needed, fill in the rows, upload the file, and monitor the task in the Task Drawer.

​

API workflow

curl --location --request POST "https://api.unibee.dev/merchant/subscription/active_subscription_import" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalSubscriptionId": "legacy-sub-1001",
    "planId": 456,
    "email": "user@example.com",
    "gateway": "stripe",
    "stripeUserId": "cus_123",
    "stripePaymentMethod": "pm_123",
    "currentPeriodStart": "2024-07-01 00:00:00",
    "currentPeriodEnd": "2024-08-01 00:00:00",
    "billingCycleAnchor": "2024-07-01 00:00:00",
    "firstPaidTime": "2024-06-15 00:00:00",
    "createTime": "2024-06-01 00:00:00"
  }'

• After import:
  • Subscription status = Active, type = UniBeeControl.
  • UniBee issues a zero-amount “catch-up” invoice so reports stay consistent.
  • User defaults (country, gateway, payment method) update.
  • Webhooks fire:
    • subscription.import.created (new record)
    • subscription.import.override (overwriting an existing import by the same admin)
    • Downstream events triggered by the zero invoice, such as invoice.paid and user.metric.update, so your billing system sees a consistent timeline.
  • Overrides are only allowed when the original subscription was imported by the same admin (metadata guard).

​

3.4 Subscription history import

​

UI workflow

1. Go to Subscription → Subscription List.
2. Click the Import button and select Import subscription history.
3. Download the template, fill it out, upload, and track the background task just like other imports.

​

API workflow

curl --location --request POST "https://api.unibee.dev/merchant/subscription/history_subscription_import" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalSubscriptionId": "legacy-sub-1001",
    "planId": 456,
    "email": "user@example.com",
    "gateway": "stripe",
    "currentPeriodStart": "2024-05-01 00:00:00",
    "currentPeriodEnd": "2024-06-01 00:00:00",
    "totalAmount": 9900
  }'

• After import:
  • UniBee creates an Expired subscription record plus a timeline slice for reporting.
  • It does not create a live subscription or trigger billing—it is purely historical.
  • Duplicate rows are rejected unless they belong to the same admin import.
  • No webhook fires; rely on Activity Logs.

​

3.5 Import flow (same for every task)

1. Download the template → fill one row per record.
2. Upload the file via the modal. UniBee immediately enqueues a background job.
3. Monitor progress in the Task Drawer (Queued → Running → Succeeded/Failed).
4. Download the annotated result file and check the ImportResult column.
5. Fix failed rows only, then re-upload.

​

4. Export playbook

​

4.1 Exports from list pages

• Users: userId, externalUserId, email, status, countryCode, defaultGatewayId, timestamps.
• Plans: planId, externalPlanId, planName, planType, amount, currency, interval, trial info.
• Subscriptions: subscriptionId, externalSubscriptionId, planName, status, gateway, amount, currency, currentPeriodStart/End, userId.
• Transactions / Invoices: invoice/payment IDs, statuses, totalAmount, taxAmount, currency, paymentMethod, gateway, timestamps.

​

4.2 Reports & Export Reports center

​

4.3 API-driven exports

1. POST /merchant/task/new_export with task name (e.g., UserExport, SubscriptionExport, InvoiceExport, CreditTransactionExport, PlanExport, DiscountExport, UserDiscountExport, MultiUserDiscountExport). Include:
   • payload: filters (date range, plan IDs, statuses, etc.).
   • exportColumns (optional): specify exact columns.
   • format: xlsx (default) or csv.
2. GET /merchant/task/list to poll for status and retrieve downloadUrl.

​

5. Validation & go-live checklist

1. Spot-check – Open a few imported users/plans/subscriptions in the UI to confirm values (amounts, cycles, payment method, etc.).
2. Billing smoke test – For active subscriptions, trigger a manual invoice or wait for the next renewal to ensure auto-charge succeeds with the imported payment token.
3. Audit trail – Admin Management → Activity Logs shows ImportNew, ImportOverride, and export events. Download logs if you need compliance evidence.
4. Communicate – Share final task IDs and validation notes with finance/support so everyone knows when UniBee becomes the source of truth.

​

6. Troubleshooting & support

• Upload rejected immediately → Most likely an outdated template or renamed columns. Download a fresh copy and reapply your data.
• “Task not found” → Check spelling/casing of the task parameter (e.g., ActiveSubscriptionImport).
• Gateway errors → Ensure Stripe/PayPal gateways are configured in UniBee; imports validate tokens against your credentials.
• Task stuck in “Running” → Large files can take several minutes. If still running after ~30 minutes, download the task log or contact UniBee Support with the task ID.
• Encoding issues → Save CSV files in UTF‑8, especially if your data includes non-English characters.

​

7. Related resources

• User import/export walkthrough
• Subscription import API reference
• Reporting overview