Paysafe.Scheduler.Subscriptions (Paysafe v1.0.0)

Subscription operations for the Paysafe Payment Scheduler API.

A Subscription binds a customer (via multi-use token) to a Plan, creating the recurring billing schedule.

Flow

Customer makes first payment → you get a single-use token (SUT).
Convert SUT to multi-use token (MUT) via Paysafe.Payments.Customers.create_payment_handle/4.
Create a subscription using the MUT and a plan ID.
Paysafe handles all subsequent billing cycles automatically.

Subscription lifecycle

FUTURE → ACTIVE → SUSPENDED → ACTIVE (re-activated)
                 ↘ CANCELLED
                 ↘ EXPIRED
                 ↘ COMPLETED (all cycles done)

Summary

Functions

cancel(config, subscription_id, opts \\ [])

Cancel a subscription immediately.

create(config, params, opts \\ [])

Create a subscription.

get(config, subscription_id, opts \\ [])

Retrieve a subscription by ID.

list(config, opts \\ [])

List subscriptions with optional filtering.

reactivate(config, subscription_id, opts \\ [])

Re-activate a suspended subscription. The last failed payment will be retried; subsequent cycles resume on their original schedule.

suspend(config, subscription_id, opts \\ [])

Suspend a subscription (pauses billing; can be re-activated).

update(config, subscription_id, params, opts \\ [])

Update a subscription.

Functions

cancel(config, subscription_id, opts \\ [])

@spec cancel(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Cancel a subscription immediately.

create(config, params, opts \\ [])

@spec create(Paysafe.Config.t(), map(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Create a subscription.

Parameters

:plan_id (required) — ID of the billing plan.
:merchant_customer_id (required) — Your customer identifier.
:payment_handle_token (required) — Multi-use token for recurring billing.
:merchant_ref_num (required) — Unique subscription reference.
:amount — Override the plan amount for this subscriber.
:start_date — ISO 8601 date. Defaults to today.
:num_payments — Override the plan's total payment count.
:trial_amount — Override the plan's trial amount.
:initial_amount — Charge a one-time setup fee on the first cycle.

get(config, subscription_id, opts \\ [])

@spec get(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Retrieve a subscription by ID.

list(config, opts \\ [])

@spec list(
  Paysafe.Config.t(),
  keyword()
) :: {:ok, [Paysafe.Types.Subscription.t()]} | {:error, Paysafe.Error.t()}

List subscriptions with optional filtering.

Options

:plan_id — Filter by plan.
:status — Filter by subscription status.
:merchant_customer_id — Filter by customer.
:limit / :offset — Pagination.

reactivate(config, subscription_id, opts \\ [])

@spec reactivate(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Re-activate a suspended subscription. The last failed payment will be retried; subsequent cycles resume on their original schedule.

suspend(config, subscription_id, opts \\ [])

@spec suspend(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Suspend a subscription (pauses billing; can be re-activated).

update(config, subscription_id, params, opts \\ [])

@spec update(Paysafe.Config.t(), String.t(), map(), keyword()) ::
  {:ok, Paysafe.Types.Subscription.t()} | {:error, Paysafe.Error.t()}

Update a subscription.

Common updates

Add extra cycles: pass num_cycles to extend billing.
Apply a discount: pass discount_amount and discount_num_payments.
Suspend: pass status: "SUSPENDED".
Cancel: use cancel/3 instead.

Notes

Keep amount increases below 20% per card scheme guidelines.
When re-activating a suspended subscription, the last failed payment is retried.