Subscriptions

Prerequisites

To create a subscription, you need to have a product that is:

• configured
• has a valid price
• is activated
• has assigned components

The product, components and variants can be created in the administration. See Products Pricing for more information.

Create a debitor

To create a subscription, you need to have a debitor.

See Debitors for more information.

Create a subscription

Subscription can be created in multiple ways. The most simple way is to create a subscription from a cart. This is done by calling the createProductCart method of the CartProductService class:

<?php

use Fynn\Sdk\V1\Checkout\CartProductService;

$cartProductService = new CartProductService($client);

$request = new CreateProductCartRequest(
    $debitorId, // The ID of the debitor which subscribes to the product
    $productId, // The ID of the product that should be subscribed to - the product must be activated
    $trialPeriod // The trial period formatted like "14D" (14 days), "1M" (1 month) or "1Y" (1 year)
);

$component = new CreateProductCartComponentRequest(
    $componentId, // The ID of the component that should be subscribed to
    $variantId, // The ID of the variant that should be subscribed to
    $quantity // The quantity of the component that should be subscribed to
);

$request->addComponent($component);
$createCartResponse = $cartProductService->createProductCart($request);

Trial period

The trial period will be applied to the whole cart. The payment will be first executed after the trial period is over.

Generate a checkout URL

The checkout URL can be generated by calling the generateCartLink method of the CartProductService class.

For more information about the checkout process, see Checkout.

Pause a subscription

A subscription can be paused by calling the pauseSubscription method of the SubscriptionService class:

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionService->pauseSubscription($subscriptionId);

During the pause, the subscription will not be billed. The subscription will be billed again when the subscription is resumed.

Resume a subscription

A subscription can be resumed by calling the resumeSubscription method of the SubscriptionService class:

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionService->resumeSubscription($subscriptionId);

Cancel a subscription

A subscription can be canceled by calling the cancelSubscription method of the SubscriptionService class.

If the subscription is in trial-phase you cannot cancel the subscription. You need to call the cancelTrial method.

<?php
use Fynn\Sdk\V1\Subscription\SubscriptionService;
use Fynn\Sdk\V1\Subscription\Request\CancelSubscriptionRequest

$subscriptionService = new SubscriptionService($client);
$subscriptionCancelRequest = new CancelSubscriptionRequest(new DateTime());

$subscriptionService->cancelSubscription($subscriptionId, $subscriptionCancelRequest);

The subscription will be canceled immediately, if no cancellation date is specified. Nevertheless, the subscription will be billed until the end of the billing period and until the earliest cancellation date.

Change subscription component quantity

The quantity of a subscription component can be changed by calling the changeSubscriptionComponentQuantity method of the SubscriptionService class:

<?php
use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$request = new \Fynn\Sdk\V1\Subscription\Request\ChangeSubscriptionComponentQuantityRequest(
    1,
    new DateTime('2021-01-01 15:00:00'), // The date from which the quantity should be changed, if not specified, the current date-time will be used
);

$subscriptionService->changeSubscriptionComponentQuantity($subscriptionComponentId, $request);

The quantity of the subscription component will be changed immediately, if no date is specified.

The price of the subscription component will be prorated from last billing until the specified change date for the old quantity. The price of the subscription component will be prorated from the specified change date until the next billing for the new quantity.

Get subscription products

The products of a subscription can be retrieved by calling the getSubscriptionProducts method of the SubscriptionService class:

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionProducts = $subscriptionService->getSubscriptionProducts($subscriptionId);

The subscription products will be returned as an array of SubscriptionProductResponse objects.

Trials

Create a trial

A trial can be created by calling the activateSubscription method of the SubscriptionService class. Provide there a trial period.

info

The period is specified in the following format: 1M (1 month), 1Y (1 year), 1W (1 week), 1D (1 day), 1H (1 hour), 1M (1 minute), 1S (1 second). (It is not a DateInterval compatible string!).

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionService->activateSubscription($subscriptionId, $trialPeriod);

Cancel a trial

A trial can be canceled by calling the cancelTrial method of the SubscriptionService class.

The trial will be canceled immediately, no invoice will be created.

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionService->cancelTrial($subscriptionId);

Extend a trial

A trial can be extended by calling the extendTrial method of the SubscriptionService class:

<?php

use Fynn\Sdk\V1\Subscription\SubscriptionService;

$subscriptionService = new SubscriptionService($client);

$subscriptionService->extendTrial($subscriptionId, $trialPeriod);

info

A trial can only be extended if the subscription is in trial.