Updating Subscriptions

Updating user subscriptions

The update subscription API allows you to make changes to an active user subscription. These changes can be changes to the recurring price, to the number of seats (quantity) or moving subscribers between plans.

API Endpoint

The endpoint for the subscriptions update API is: https://vendors.paddle.com/api/2.0/subscription/users/update

A list of accepted fields and their meanings is below.

Field Required Description
vendor_id Yes Your vendor ID.
vendor_auth_code Yes Your vendor auth code.
subscription_id Yes The ID of the subscription you’re updating.
quantity Yes The quantity to be applied to the user subscription. If there are no changes to it you will still need to set it with the current value when calling this API. For non-quantity subscription plans, always set the Quantity to 1.
recurring_price No The new recurring price per unit to apply to a quantity enabled subscription. Please note this is a singular price, i.e 11.00.
currency Variable (Required if setting recurring_price) The currency that the recurring price should be charged in. E.g. USD,GBP, EUR, etc.
bill_immediately No (Defaults to false) If the subscription should bill for the next interval at the revised figures immediately.
plan_id No The new plan ID to move the subscription to.
prorate No (Defaults to true) Whether the change in subscription should be prorated.
keep_modifiers No (Defaults to true) Retain the existing modifiers on the user subscription.

Examples

Curl and JSON payload example of a request to update the quantity to 7 and unit price to $11 for the user subscription 12345.

Example Request


curl -X POST \
  -d 'vendor_id=123' \
  -d 'vendor_auth_code=456bd...' \
  -d 'subscription_id=12345' \
  -d 'quantity=7' \
  -d 'recurring_price=11.00' \
  -d 'currency=USD' \
https://vendors.paddle.com/api/2.0/subscription/users/update
{
   "quantity" : "7",
   "vendor_auth_code" : "456bd...",
   "vendor_id" : "123",
   "recurring_price" : 11,
   "currency" : "USD",
   "subscription_id" : "12345"
}

Example Response

{
    "success": true,
    "response": {
        "subscription_id": 12345,
        "user_id": 425123,
        "plan_id": 525123,
        "next_payment": {
            "amount": 144.06,
            "currency": "GBP",
            "date": "2018-02-15"
        }
    }
}

Read more about quantity subscriptions

Curl and JSON payload example of a request to move the user subscription 12345 to plan 678910.

Example Request


curl -X POST \
  -d 'vendor_id=123' \
  -d 'vendor_auth_code=456bd...' \
  -d 'subscription_id=12345' \
  -d 'quantity=1' \
  -d 'plan_id=678910' \
https://vendors.paddle.com/api/2.0/subscription/users/update
{
   "quantity" : "1",
   "vendor_auth_code" : "456bd...",
   "vendor_id" : "123",
   "plan_id" : "678910",
   "subscription_id" : "12345"
}

Example Response

{
    "success": true,
    "response": {
        "subscription_id": 12345,
        "user_id": 425123,
        "plan_id": 525123,
        "next_payment": {
            "amount": 144.06,
            "currency": "GBP",
            "date": "2018-02-15"
        }
    }
}

Notes:

  • Subscribers on non-quantity plans can move to quantity plans but not the inverse.
  • Subscribers cannot be moved to a plan where frequency is lower than their current plan.
  • Subscribers cannot be moved to a plan where the current currency is not enabled.
  • Subscribers cannot be moved to another plan whilst still on trial.
  • The currency of an existing subscription cannot be changed.
  • Recurring coupons will be removed when moving subscribers between plans.

Please see List Users to get the list of subscribed users.

Failed Response Example

If you try to update the quantity of a non-quantity subscription you will get the following error code.

{
  "success": false,
  "error": {
  "code": 173,
  "message": "The subscription does not allow quantities to be set."
  }
}

Old upgrades and downgrades API reference.

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.