Docs

PayPal Subscription Modes

Updated on

The PayPal gateway supports two different subscription modes: PayPal Subscriptions and  Payment Vaulting.

 These modes work differently and require different configurations.

Before setting up subscriptions, choose the mode that best fits your store’s needs.

When to use PayPal SubscriptionsWhen to use Payment Vaulting
PayPal handles renewals automaticallyStore handles renewals using saved payment method
PayPal retry logic for failed paymentsMerchant manages retry logic
Minimal configurationFull control over subscription changes
PayPal manages subscription lifecycleWooCommerce/Sublium manages subscription lifecycle

How To Select Subscription Mode 

You can select your mode at:

WooCommerce → Settings → Payments → PayPal, and under “Express Checkout Settings” choose Subscription mode. 

Note: The PayPal Vaulting option depends on your PayPal account settings. Our plugin dynamically checks whether Vaulting is enabled in your account. If your account does not support Vaulting, the option will appear as disabled. To use Vaulting, make sure it is enabled in your PayPal account first.

Subscription mode selection in the PayPal gateway settings

PayPal Subscriptions

PayPal manages the subscription and automatically charges the customer on renewal. Your store does not handle renewal payments.

Flow at Checkout and Renewal:

StepWhat Happens
Customer checkoutCustomer selects a subscription product.
Plugin actionCreates PayPal Billing Plan (P-XXXXX) and PayPal Subscription (I-XXXXX) via PayPal API.
Customer approvalCustomer approves subscription in PayPal popup.
Payment storagePayPal stores payment method as part of the subscription agreement (Vault not required).
RenewalPayPal automatically charges the customer.
Store notificationsWebhooks notify your store: PAYMENT.SALE.COMPLETED, BILLING.SUBSCRIPTION.ACTIVATED.

What Gets Created:

  • PayPal Subscription ID (I-XXXXX)
  • PayPal Plan ID (P-XXXXX)
  • WooCommerce/Sublium subscription linked to PayPal subscription

Requirements:

  • PayPal Business account
  • PayPal connected via OAuth or API credentials
  • Webhooks configured

Troubleshooting:

  • Subscription not created → Check API credentials and webhook configuration
  • Renewals not showing → Verify webhook delivery

Learn More: For more details on PayPal Vaulting mode, click here.