/ 
WWW-PayPal-0.001
/ WWW::PayPal::API::Subscriptions

NAME

WWW::PayPal::API::Subscriptions - PayPal Billing Subscriptions API (v1)

VERSION

version 0.001

SYNOPSIS

# Per-user subscription
my $sub = $pp->subscriptions->create(
    plan_id    => $plan->id,
    return_url => 'https://example.com/paypal/sub/return',
    cancel_url => 'https://example.com/paypal/sub/cancel',
    subscriber => {                           # optional
        email_address => 'buyer@example.com',
    },
);

my $approve_url = $sub->approve_url;          # redirect the buyer here

# ... after approval ...
my $same = $pp->subscriptions->get($sub->id);
print $same->status;                          # ACTIVE

# Lifecycle
$pp->subscriptions->suspend($sub->id, reason => 'User paused');
$pp->subscriptions->activate($sub->id, reason => 'Resumed');
$pp->subscriptions->cancel($sub->id, reason => 'User cancelled');

DESCRIPTION

Controller for PayPal's Billing Subscriptions API — the per-user, recurring-payment side of the subscription flow. A subscription references a plan (which in turn references a product).

After the buyer approves the subscription at "approve_url", PayPal will automatically bill them on the plan's schedule (e.g. monthly). No per-cycle server action is needed — listen for webhooks (BILLING.SUBSCRIPTION.*, PAYMENT.SALE.COMPLETED) if you want to react to charges.

create

my $sub = $pp->subscriptions->create(
    plan_id    => $plan_id,
    return_url => '...',
    cancel_url => '...',
    subscriber => { email_address => '...' },   # optional
    custom_id  => 'user-42',                    # optional merchant ref
);

Creates a subscription and returns a WWW::PayPal::Subscription. The buyer must be redirected to approve_url before PayPal starts billing.

get

my $sub = $pp->subscriptions->get($id);

suspend

activate

cancel

$pp->subscriptions->suspend($id, reason => 'User paused');
$pp->subscriptions->activate($id, reason => 'Resumed');
$pp->subscriptions->cancel($id, reason => 'User cancelled');

Lifecycle transitions. reason is required by PayPal but defaults to 'not specified' if you don't pass one.

capture

$pp->subscriptions->capture($id,
    amount => { currency_code => 'EUR', value => '10.00' },
    note   => 'Reason shown to payer',
);

Captures an outstanding balance on a subscription (e.g. after failed auto-bill).

transactions

my $txs = $pp->subscriptions->transactions($id,
    start_time => '2026-01-01T00:00:00Z',
    end_time   => '2026-12-31T23:59:59Z',
);

Returns the raw transactions list for a subscription in the given time window.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-paypal/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.