Subscriptions API

July 30, 2026

Create, retrieve, update and cancel FlowAlp Pay subscriptions via API, with recurring billing intervals, periods and VAT parameters.

A Subscription is a recurring billing agreement that FlowAlp Pay manages for you: the platform charges the customer's stored payment method at every payment interval. The endpoints below create a subscription for an existing contact, look subscriptions up, adjust the billed amount and cancel the agreement. If you want customers to start a subscription through the hosted checkout instead, create a Gateway with the subscriptionState, subscriptionInterval, subscriptionPeriod and subscriptionCancellationInterval parameters — the concept is explained in Subscriptions and recurring payments.

The Subscription API is in productive use, but parts of its documented behaviour are still evolving. If a field responds differently than described here, treat the live API response as authoritative and contact support before relying on it.

Create a Subscription

POSThttps://api.pay.flowalp.com/v1.16/Subscription/v1.14 · v1.15 · v1.16

All interval parameters use ISO 8601 duration strings as understood by PHP's DateInterval — for example P1D (one day), P1W (one week), P1M (one month) or P1Y (one year).

Request parameters

Parameter	Type	Description
instance	string (required)	Query parameter: name of your instance (tenant).
userId	string (required)	ID of the contact to bill. You receive it in the transaction webhook of the initial payment.
psp	string (required)	Numeric ID of the payment provider to charge. Look it up with the payment providers endpoint.
amount	string (required)	Amount charged at each interval, as a numeric value in minor units (`1490` = CHF 14.90).
currency	string (required)	ISO currency code of the payment, for example `CHF`.
purpose	string (required)	What the customer is paying for.
paymentInterval	string (required)	How often the amount is charged, e.g. `P1M` for monthly billing.
period	string (required)	Total duration of the subscription, e.g. `P1Y`.
cancellationInterval	string (required)	Cancellation notice period, e.g. `P1M`.
referenceId	string	Your internal reference; it is sent back in webhook notifications so you can match the subscription to your records.
vatRate	string	VAT rate as a percentage value.

Create a subscriptionbash

curl -X POST "https://api.pay.flowalp.com/v1.16/Subscription/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "12",
    "psp": "4",
    "amount": "1490",
    "currency": "CHF",
    "purpose": "Streaming plan",
    "paymentInterval": "P1M",
    "period": "P1Y",
    "cancellationInterval": "P1M",
    "referenceId": "PLAN-2026-042"
  }'

Create a subscription (PHP SDK)PHP

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Subscription;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$subscription = new Subscription();
$subscription->setUserId(12);
$subscription->setPsp(4);
$subscription->setAmount(1490);
$subscription->setCurrency('CHF');
$subscription->setPurpose('Streaming plan');
$subscription->setPaymentInterval('P1M');
$subscription->setPeriod('P1Y');
$subscription->setCancellationInterval('P1M');

try {
    $response = $client->create($subscription);
    echo $response->getId();
} catch (Exception $e) {
    error_log('Subscription create failed: ' . $e->getMessage());
}

Retrieve a Subscription

GEThttps://api.pay.flowalp.com/v1.16/Subscription/{id}/v1.14 · v1.15 · v1.16

Parameter	Type	Description
id	integer (required)	Path parameter: ID of the subscription to retrieve.
instance	string (required)	Query parameter: name of your instance (tenant).

Retrieve a subscriptionbash

curl "https://api.pay.flowalp.com/v1.16/Subscription/84/?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

List Subscriptions

GEThttps://api.pay.flowalp.com/v1.16/Subscription/v1.14 · v1.15 · v1.16

Parameter	Type	Description
instance	string (required)	Query parameter: name of your instance (tenant).
orderByStartDate	string	`ASC` (default) or `DESC` — sort order by subscription start date.
limit	integer	Maximum number of rows to return. Defaults to `10`.
offset	integer	Number of rows to skip. Defaults to `0`.

List subscriptions (PHP SDK)PHP

<?php
use FlowAlpPay\Models\Request\Subscription;

// $client: same constructor as in the create example above
$request = new Subscription();
$request->setOrderByStartDate('DESC');
$request->setLimit(10);

try {
    $subscriptions = $client->getAll($request);
    foreach ($subscriptions as $subscription) {
        echo $subscription->getId() . ': ' . $subscription->getStatus() . PHP_EOL;
    }
} catch (Exception $e) {
    error_log('Subscription list failed: ' . $e->getMessage());
}

Update a Subscription

Changes apply to the next billing cycle. Adjusting vatRate on subscriptions backed by products is supported since API version 1.13.

PUThttps://api.pay.flowalp.com/v1.16/Subscription/{id}/v1.14 · v1.15 · v1.16

Parameter	Type	Description
id	integer (required)	Path parameter: ID of the subscription to update.
instance	string (required)	Query parameter: name of your instance (tenant).
amount	string	New amount in minor units, charged from the next payment interval on.
currency	string	ISO currency code of the payment.
purpose	string	New payment purpose.
vatRate	string	New VAT rate as a percentage value.

Update a subscriptionbash

curl -X PUT "https://api.pay.flowalp.com/v1.16/Subscription/84/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1990",
    "currency": "CHF",
    "purpose": "Streaming plan Plus"
  }'

Update a subscription (PHP SDK)PHP

<?php
use FlowAlpPay\Models\Request\Subscription;

// $client: same constructor as in the create example above
$subscription = new Subscription();
$subscription->setId(84);
$subscription->setAmount(1990);
$subscription->setCurrency('CHF');
$subscription->setPurpose('Streaming plan Plus');

try {
    $client->update($subscription);
} catch (Exception $e) {
    error_log('Subscription update failed: ' . $e->getMessage());
}

Cancel a Subscription

Cancelling stops the recurring billing of the subscription. The operation is exposed through the official SDK, where cancellation is issued as a DELETE request on the subscription resource.

DELETEhttps://api.pay.flowalp.com/v1.16/Subscription/{id}/v1.14 · v1.15 · v1.16

Cancel a subscriptionbash

curl -X DELETE "https://api.pay.flowalp.com/v1.16/Subscription/84/?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Cancel a subscription (PHP SDK)PHP

<?php
use FlowAlpPay\Models\Request\Subscription;

// $client: same constructor as in the create example above
$subscription = new Subscription();
$subscription->setId(84);

try {
    $client->cancel($subscription);
} catch (Exception $e) {
    error_log('Subscription cancel failed: ' . $e->getMessage());
}

Response

Subscription endpoints reply with the usual envelope: status plus a data array of subscription objects. paymentInterval echoes the billing rhythm, valid_until shows how long the current period is paid for, and the embedded invoice and contact objects describe what is billed to whom.

Sample responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 84,
      "uuid": "a5e0c919",
      "status": "active",
      "start": "2026-01-12",
      "end": null,
      "valid_until": "2027-01-12",
      "paymentInterval": "P1M",
      "invoice": {
        "number": "Streaming plan",
        "currency": "CHF",
        "referenceId": "PLAN-2026-042",
        "originalAmount": 1490,
        "refundedAmount": 0
      },
      "contact": {
        "id": 12,
        "uuid": "4ab402a9",
        "firstname": "Anna",
        "lastname": "Keller",
        "email": "anna.keller@example.com",
        "countryISO": "CH"
      }
    }
  ]
}

Errors

HTTP status	Meaning
400	Malformed request — the `message` field of the error body describes the exact problem.
404	No subscription with the given ID exists on this instance.

Recurring charges appear as regular transactions — track them with List and retrieve Transactions or via webhook events. To find the provider IDs accepted by psp, call the payment providers endpoint.

Subscriptions API

Create a Subscription#

Request parameters#

Retrieve a Subscription#

List Subscriptions#

Update a Subscription#

Cancel a Subscription#

Response#

Errors#