---
title: "Import Subscriptions"
slug: "import-subscriptions"
updated: 2026-07-09T05:04:27Z
published: 2026-07-09T05:04:27Z
canonical: "help.frisbii.com/import-subscriptions"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.frisbii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Subscriptions

Use this flow to import existing subscriptions from an external system into Frisbii Media. A typical use case is a migration: the subscription continues in Frisbii Media as if it had originated there, including invoicing and renewal.

> [!NOTE]
> **Prerequisite:** You must create a matching subscription offer in the [Frisbii Media backend](/frisbii-media/docs/angebote) first. The examples below assume offer ID `O_FAK3OFF3R`. At the moment, order imports only work with subscription offers — not with single-product offers.

---

## Overview

The import requires five steps in order:

1. Create the customer
2. Create a delivery address
3. Create a payment method
4. Create the order (the subscription import itself)
5. Verify: find the imported subscription

---

## Step 1 – Create the customer

```php
// @see https://api.frisbii-media.com/#tag/Customers/operation/createCustomer
$customerData = [
    'invoiceEmail'       => 'office@company.com',    // used only for invoice emails
    'username'           => 'kitty_207',              // must be unique in Frisbii Media
    'email'              => 'kitty.miller@company.com', // login email, must be unique
    'pseudoEmail'        => false, // true: generate a pseudo email for customers without one
    'salutation'         => 'MR',  // one of: NONE, MRS, MR, DIVERSE
    'firstName'          => 'Kitty',
    'lastName'           => 'Miller',
    'birthday'           => '2000-07-20T00:00:00.000Z',
    'language'           => 'de',
    'registrationSource' => 'Import-' . (new DateTime())->format('Y-m-d'),
    'customerId'         => '12345',                               // numeric, unique
    'externalSystemId'   => '550e8400-e29b-41d4-a716-446655440000', // alphanumeric, unique
];
$customer = json_decode($client->request('POST', '/customers', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $customerData,
])->getBody()->getContents(), true);
```

See [Customer Management](/frisbii-media/docs/customer-management) for field descriptions and the `customerId` vs. `externalSystemId` distinction.

---

## Step 2 – Create a delivery address

A country field is required for subscription imports.

```php
// @see https://api.frisbii-media.com/#tag/Addresses/operation/createAddress
$addressData = [
    'type'            => 'DELIVERY', // one of: DELIVERY, INVOICE
    'preferred'       => true,       // preferred address is used automatically in checkout
    'salutation'      => 'MR',
    'firstName'       => 'Kitty',
    'lastName'        => 'Miller',
    'title'           => '',         // e.g. 'Dr'
    'country'         => 'DE',       // required for imports
    'customerId'      => $customer['customerId'],
    'businessAddress' => false,      // true: show company fields
];
$deliveryAddress = json_decode($client->request('POST', '/addresses', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $addressData,
])->getBody()->getContents(), true);
```

---

## Step 3 – Create a payment method (SEPA bank account)

```php
// @see https://api.frisbii-media.com/#tag/Payment-Methods/operation/createBankAccount
$sepaData = [
    'customerId'  => $customer['customerId'],
    'owner'       => "{$customer['firstName']} {$customer['lastName']}",
    'iban'        => 'DE65500105173367173799',
    'invalid'     => false,       // true: hide account from customer, skip for payments
    'mandateId'   => 'DE0815',    // mandate reference from existing SEPA agreement
    'mandateDate' => '2022-10-10T23:44:11.357Z',
];
$paymentAccount = json_decode($client->request('POST', '/paymentMethods/bankAccounts', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $sepaData,
])->getBody()->getContents(), true);
```

---

## Step 4 – Create the order (import)

```php
// @see https://api.frisbii-media.com/#tag/Order-Imports/operation/orderImport
$import = [
    'suppressMail' => true,  // true: do not send transactional emails for this import
    'purchase'     => false, // true: treat as a purchase (generates different accounting)
    'items'        => [
        [
            'externalSystemId'   => 'Migration-4711', // your unique ID for this subscription; used to find and update it later
            'plenigoOfferId'     => 'O_FAK3OFF3R',
            'invoiceCustomerId'  => $customer['customerId'],
            'paymentMethod'      => 'BANK_ACCOUNT',
            'paymentMethodId'    => $paymentAccount['bankAccountId'],
            'deliveryCustomerId' => $customer['customerId'],
            'deliveryAddressId'  => $deliveryAddress['addressId'],
            'startDate'          => '2020-10-10T10:10:10.100Z', // when the subscription started in the source system
            'referenceStartDate' => '2023-10-10T00:00:00.000Z', // date of the last invoice in the source system (must be in the past)
            'orderDate'          => '2020-10-05T10:10:10.100Z', // when the order was created in the source system
            'endDate'            => null,                        // set a date to let the subscription expire at a specific point
            'nextBookingDate'    => '2024-10-10T00:00:00.000Z', // end of the current performance period; Frisbii Media creates the next invoice at this date
            'quantity'           => 1,
        ],
    ],
];
$importStatus = json_decode($client->request('POST', '/imports/orders', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $import,
])->getBody()->getContents(), true);
```

### Key date fields explained

| Field | Description |
| --- | --- |
| `startDate` | When the subscription originally started. Historical date. |
| `referenceStartDate` | The date of the last invoice issued in your source system. Frisbii Media uses this as the billing anchor. Must be in the past. |
| `orderDate` | When the order was created in your source system. |
| `nextBookingDate` | The end of the current prepaid period. Frisbii Media will generate a new invoice on this date and take over billing from here. |
| `endDate` | If set, the subscription ends on this date. Leave `null` for open-ended subscriptions. |

---

## Step 5 – Verify: find the imported subscription

Use your `externalSystemId` to confirm the import succeeded and retrieve the Frisbii Media subscription ID for future operations.

```php
$importedSubscription = json_decode($client->request('GET',
    '/subscriptions?externalSystemId=Migration-4711',
    ['headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9]]
)->getBody()->getContents(), true)['items'][0] ?? null;
```

---

## API reference

- [orderImport](https://api.plenigo.com/#tag/Order-Imports/operation/orderImport)
- [createAddress](https://api.plenigo.com/#tag/Addresses/operation/createAddress)
- [createBankAccount](https://api.plenigo.com/#tag/Payment-Methods/operation/createBankAccount)

---