Manage unscheduled subscriptions

Overview

Once you have a checkout page that can handle unscheduled subscriptions, it is time to implement functionality on your backend to manage these unscheduled subscriptions:

• Charge sunscheduled ubscriptions: You can charge one or multiple unscheduled subscriptions at once. Charging an unscheduled subscription is an asynchronous operation. You create a new bulk charge operation and then retrieve the status of the operation at a later stage.

Retrieve unscheduled subscription details

Before you can charge an unscheduled subscription, you need to obtain the identifier of the unscheduled subscription. You can get the unscheduled subscription identifier from Checkout Portal or the Payment API. The guide Unscheduled Subscriptions (uCoF) describes how to retrieve unscheduled subscription details, including the unscheduledSubscriptionId. Please see Retrieve unscheduled subscription ID using the Payment API for more details.

Charge an unscheduled subscription

When a new unscheduled subscription payment has been created and you have retrieved the unscheduledSubscriptionId, you can initiate new payments associated with the unscheduled subscription. You are free to create arbitrary payments with completely different order items and amounts.

When charging an unscheduled subscription, you need to provide a full order that specifies what you are charging your customer for. Use the Charge unscheduled subscription method to charge an unscheduled subscription.

Here is an example:

<?php

$curl = curl_init();

The payload is typically created dynamically by your backend. But if you just want to try it out, you can use the following hard-coded request body that charges for a single item. Remember to replace <UNSCHEDULEDSUBSCRIPTION_ID> with a valid unscheduled subscription identifier.

{
    "unscheduledSubscriptions": [
        {
            "unscheduledSubscriptionId": "<UNSCHEDULEDSUBSCRIPTION_ID>",

Charge multiple unscheduled subscriptions

It is possible to charge multiple unscheduled subscriptions in bulk. In a single API call, you can charge an arbitrary amount of unscheduled subscriptions. The unscheduled subscription identifiers are typically saved on your side so that you can compose charge requests of all your unscheduled subscriptions.

Here is an example of a payload which charges two active unscheduled subscriptions. Remember to replace <UNSCHEDULEDSUBSCRIPTION_ID_1> and <UNSCHEDULEDSUBSCIRIPTION_ID_2> with actual unscheduled subscription identifiers before posting the request.

{
    "externalBulkChargeId": "1002",
     "notifications": {
        "webhooks": [ ]

The example also demonstrates that it is possible to add an array of webhooks to the request so that you can track the events triggered by the bulk charge operation. You can find more information about the notifications property in the API reference.

If the charge request was sucessful, a 202 HTTP status code is returned with a new bulk identifier:

{
    "bulkId": "d6c11ab596184414bef9adf20936e583"
}

A successful response does not imply that all of the unscheduled subscriptions have been charged successfully. However, you can use the bulkId returned in the response body to retrieve details about a bulk charge operation, as shown in the following step.

Retrieve bulk charge details

When you perform a bulk charge operation, unscheduled subscriptions might fail for various reasons, for example:

• Not enough funds on the card, which makes the bank reject the reservation. In this case you can inform your customer about the situation and try to do a new charge.

• The card has become invalid because it has expired, has been reported stolen, etc. In this case you need to update the unscheduled subscription.

To retrieve the status of a bulk charge operation, you can use the method Retrieve bulk unscheduled charges.

The response is paginated since a lot of unscheduled subscriptions are potentially being processed. You have two options when specifying the range of charges you want to retrieve:

1. Use skip and take.
2. Use pageNumber and pageSize.

In the sample code below, skip and take is used to specify that the first 10 unscheduled subscriptions should be retrieved:

<?php

$secretKey = "<YOUR_SECRET_API_KEY>";
$bulkId = "<BULK_ID>";

The following response from the server indicates that all unscheduled subscriptions were returned ("more": false) and that all charges have completed successfully:

{
    "page": [
        {
            "unscheduledSubscriptionId": "6946cde8d7a049dc89145224088b0df9",