Skip to main content

Upgrading and Downgrading Subscriptions Overview

The Change Product endpoint allows you to switch a customer's subscription to a different product, making it ideal for plan upgrades, downgrades, or product changes.This powerful API method enables you to adapt to your customers' changing needs while maintaining continuous service.

Use Cases​

Common scenarios for changing subscription products include:

  • Upgrading - Moving a customer from a basic plan to a premium plan with enhanced features
  • Downgrading - Moving a customer from a premium plan to a basic plan to better match their needs
  • Product Migration - Switching customers to a new product offering or updated service tier
  • Plan Adjustments - Changing features or service levels based on customer needs and usage patterns

Prerequisites​

Before you begin, ensure you have:

  1. An active PayPro Global merchant account
  2. The subscription ID you want to modify
  3. The new product ID you want to switch to
  4. Your API credentials:
    • Vendor Account ID - Found in Account settings > Business info
    • API Secret Key - Found in Store settings > General settings > Integration tab

API Endpoint​

Post
https://store.payproglobal.com/api/Subscriptions/ChangeProductDocusaurus themed imageDocusaurus themed image
Request Parametersapplication/json
UpdateProductRequestModel
object
productId
integer
required
The ID of the new product that will be updated in the subscription.
quantity
integer
optional
The new product quantity you want to apply.
sendCustomerNotification
boolean
optional
Possible values are true or false.
If true, it sends a customer an email that informs
about the changed subscription details, false otherwise.
By default, the customer doesn't receive any email notification.
subscriptionId
integer
required
The subscription ID that needs to be updated.
vendorAccountId
integer
required
The vendor account ID identifies your PayPro Global account.
It can be found in Account settings > Business info.
apiSecretKey
string
required
The vendor account API secret key is a unique key
that was generated specifically for authenticating API requests.
It can be found in Store settings > General settings > Integration tab.
Response Parametersapplication/json
UpdateProductResponseModel
object
request
object
productId
integer
The ID of the new product that will be updated in the subscription.
quantity
integer
The new product quantity you want to apply.
sendCustomerNotification
boolean
Possible values are true or false.
If true, it sends a customer an email that informs
about the changed subscription details, false otherwise.
By default, the customer doesn't receive any email notification.
subscriptionId
integer
The subscription ID that needs to be updated.
vendorAccountId
integer
The vendor account ID identifies your PayPro Global account.
It can be found in Account settings > Business info.
apiSecretKey
string
The vendor account API secret key is a unique key
that was generated specifically for authenticating API requests.
It can be found in Store settings > General settings > Integration tab.
errors
array[object]
propertyWithError
string
propertyErrorMessages
array[string]
isSuccess
boolean
Request Sample
{
  "productId": 12345,
  "quantity": 3,
  "sendCustomerNotification": true,
  "subscriptionId": 1111111,
  "vendorAccountId": 123456,
  "apiSecretKey": "your_api_secret_key"
}
Response Sample
{
  "request": {
    "productId": 12345,
    "quantity": 3,
    "sendCustomerNotification": true,
    "subscriptionId": 1111111,
    "vendorAccountId": 123456,
    "apiSecretKey": "your_api_secret_key"
  },
  "errors": [],
  "isSuccess": true
}

Best Practices​

1. Customer Communication

Keeping your customers informed is crucial for maintaining trust and satisfaction:

  • Set sendCustomerNotification to true when making changes that affect the customer's service
  • Send additional communication through your own channels for important upgrades or downgrades to ensure the message is received
  • Provide clear information about what changes with the new product, including:
    • Feature differences between old and new products
    • Pricing changes and when they take effect
    • Any changes to billing cycles or payment dates
    • Steps customers need to take (if any)

2. Validation Before API Call

Before calling the API, validate that:

  • The subscription ID exists and belongs to the customer
  • The new product ID is valid and available
  • The customer has permission to make this change
  • The product change makes business sense (upgrade/downgrade logic)
note

The new product's features and pricing will take effect with the next billing cycle. Plan your communication and timing accordingly.

3. Proration Considerations

Understanding how product changes affect billing is essential for managing customer expectations and revenue:

Timing of Changes

Product changes become effective based on your business rules, but typically align with billing cycles. Consider:

  • When the customer will see the change reflected in their account
  • How the current billing period will be handled
  • When the new pricing will begin

Managing Billing Adjustments

PayPro Global provides several API methods to handle proration scenarios:

For Upgrades (Moving to Higher-Priced Plans):

Use the Do Reference Charge API if you need to charge the customer for the price difference on the current billing cycle. This allows you to immediately charge the prorated amount for the upgraded service during the current billing period.

For Downgrades (Moving to Lower-Priced Plans):

Use the Apply Accumulative Discount API to provide the customer with credit for the unused amount of the current billing cycle. This ensures customers receive appropriate credit when moving to a less expensive plan.

Adjusting Billing Cycle Length:

Use the Change Next Payment Date API if you need to update the length of the current billing cycle. This is useful when you want to align the billing cycle with the product change or provide extended access.

Best Practices for Proration

  • Communicate clearly - Always inform customers about any immediate charges or credits
  • Be transparent - Explain the calculation method for any proration
  • Provide documentation - Include line items in invoices showing the proration details
  • Consider customer satisfaction - Sometimes absorbing small differences can improve customer loyalty
  • Test scenarios - Verify your proration logic works correctly for various timing situations

To fully manage subscription upgrades and downgrades, you may need these additional endpoints:

Support​

For additional assistance, email us at [email protected]