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.

Prerequisite: You must create a matching subscription offer in the Frisbii Media backend 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

// @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 for field descriptions and the customerId vs. externalSystemId distinction.

Step 2 – Create a delivery address

A country field is required for subscription imports.

// @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)

// @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)

// @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

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.

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

API reference

• orderImport

• createAddress

• createBankAccount