Issue-Based Subscriptions

Issue-based subscriptions are billed by the number of issues delivered, not by a fixed time period. Instead of a recurring monthly or annual charge, the customer is invoiced after a specific number of issues has been sent or consumed.

Typical use case: a weekly magazine subscription that bills after every 12 issues.

Difference to time-based subscriptions

	Time-based	Issue-based
Billing trigger	Calendar date (e.g. monthly)	After N issues delivered
`issueBased`	`false` (default)	`true`
Cancellation dates	Based on renewal dates	Based on issue counts

Create a new issue-based order

Use issueBased: true and provide at least one entry in issueSteps with a startDate. For a new subscription, set startDate to tomorrow:

// @see https://api.frisbii-media.com/#tag/Order-Imports/operation/orderImport
$import = [
    'suppressMail' => true,
    'purchase'     => false,
    'items'        => [
        [
            'externalSystemId'   => 'IssueSub-4711',
            'plenigoOfferId'     => 'O_FAK3OFF3R',
            'invoiceCustomerId'  => $customer['customerId'],
            'issueBased'         => true,
            'issueSteps'         => [
                [
                    'startDate' => (new DateTime('tomorrow'))->format(DATE_RFC3339_EXTENDED),
                ],
            ],
            'paymentMethod'      => 'BILLING',
            'deliveryCustomerId' => $customer['customerId'],
            'deliveryAddressId'  => $deliveryAddress['addressId'],
            'quantity'           => 1,
        ],
    ],
];
$importStatus = json_decode($client->request('POST', '/imports/orders', [
    'headers' => ['X-plenigo-token' => $yourGeneratedToken],
    'json'    => $import,
])->getBody()->getContents(), true);

Migrate an existing issue-based subscription

When migrating from a source system, you need to tell Frisbii Media the subscription history: which billing steps have already occurred and how many issues remain in the current step before the next invoice.

For multi-step subscription plans (e.g. an intro price for the first 12 issues, then a regular price), pass all past steps as well.

$import = [
    'suppressMail' => true,
    'purchase'     => false,
    'items'        => [
        [
            'externalSystemId'   => 'IssueSub-4711',
            'plenigoOfferId'     => 'O_FAK3OFF3R',
            'invoiceCustomerId'  => $customer['customerId'],
            'issueBased'         => true,
            'issueSteps'         => [
                [
                    // Step 1: already completed — no openDeliveries needed
                    'startDate'      => '2020-10-10T10:10:10.100Z',
                    'openDeliveries' => 0,
                ],
                [
                    // Step 2: currently active — 2 issues remain before next invoice
                    'startDate'      => '2023-10-10T10:10:10.100Z',
                    'openDeliveries' => 2,
                    // Optional: if you want the subscription to end after these 2 issues:
                    // 'cancellationDate' => (new DateTime('today'))->format(DATE_RFC3339_EXTENDED),
                ],
            ],
            'paymentMethod'      => 'BILLING',
            'deliveryCustomerId' => $customer['customerId'],
            'deliveryAddressId'  => $deliveryAddress['addressId'],
            'quantity'           => 1,
        ],
    ],
];
$importStatus = json_decode($client->request('POST', '/imports/orders', [
    'headers' => ['X-plenigo-token' => $yourGeneratedToken],
    'json'    => $import,
])->getBody()->getContents(), true);

issueSteps field reference

Field	Description
`startDate`	When this billing step started
`openDeliveries`	Number of issues remaining before Frisbii Media triggers the next invoice. `0` means this step is already completed.
`cancellationDate`	Optional. If set, the subscription will end after the remaining `openDeliveries` are consumed.

Note on externally managed issue-based subscriptions

From a Frisbii Media perspective, there is no strong reason to import issue-based subscriptions as externally managed. Since the external system already knows the start and end dates precisely, a time-based external managed subscription achieves the same result with simpler configuration: grant access for exactly the period the subscription is active in the source system.

API reference

orderImport