Customize subscriptions

With subscription services, you may encounter scenarios where you want to customize a subscription for select customers. PayPal enables you to customize pricing and billing details for new and existing subscriptions. Common customization scenarios include:

Scenario Example
Merchants offering custom pricing based on negotiations with customers. A merchant who provides remote tech support services at a rate of $10 per person per month offers a discounted rate of $8 per person per month to a key customer.
Merchants extending a finite subscription plan for customers. A merchant who provides online music tutorials extends a 12 month subscription by one additional month to a customer who expressed interest in extending the service.
Merchants reducing the one-time setup fee for customers. A merchant who offers gym and yoga classes reduces the registration fee for an undecided customer from $20 to $10.

You can also:

  • Extend trial periods.
  • Control billing preferences based on customer profile types.
  • Set custom values for subscribers while they upgrade or downgrade between plans.
  • Set custom tier definition and price for volume-based and tiered-based subscriptions.

Example: discount subscription price

This example customizes a subscription with the following characteristics:

  • A merchant sells dog food packets.
  • The normal subscription plan is $10 per food packet per month.
  • The customer needs 20 food packets per month.
  • The merchant gives the customer a discounted rate of $8 per food packet per month.

This sample code shows how to set a discounted price when setting up a subscription:

Sample request

curl -v -k -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions \
  -H "Accept: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json" \
  -H "PayPal-Request-Id: PLAN-18062020-001" \
  -d '{
    "plan_id": "P-7K577606KK9446621L5LJHUY",
    "quantity": "20",
    "subscriber": {
        "name": {
            "given_name": "John",
            "surname": "Doe"
        },
        "email_address": "customer@example.com"
    },
    "plan": {
        "billing_cycles": [
            {
                "sequence": 1,
                "total_cycles": 0,
                "pricing_scheme": {
                    "fixed_price": {
                        "value": "8",
                        "currency_code": "USD"
                    }
                }
            }
        ]
    },
    "application_context": {
        "brand_name": "Acme Pet Food",
        "locale": "en-US",
        "user_action": "SUBSCRIBE_NOW",
        "shipping_preference": "GET_FROM_FILE",
        "payment_method": {
            "payer_selected": "PAYPAL",
            "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
        },
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
    }
}'

Limitations

Limitation Example
You can't update attributes that already passed or completed. You can’t extend a trial period after it's completed.
After you customize a subscription attribute for a subscriber, changes to the generic plan attribute won't impact this subscriber's customized subscription. A subscription plan is $10 per month. The merchant customizes the plan to $5 per month for a specific subscriber. If the merchant changes the plan price from $10 per month to $12 per month, the price of this particular subscriber remains $5 per month.
If you update subscription prices, billing cycles within 10 days aren't affected until the next billing cycle. PayPal informs existing subscribers of the price change at least 10 days in advance. You update the subscription price from $10 to $12 on the 10th of the month. This subscriber's billing cycle starts on the 15th of the month. This subscriber pays $10 for their subscription on the 15th of the month, and on the following month pays $12.

See also