Skip to content

Change product


Target audience: Developers

Upgrade, downgrade or change product


Upgrade, downgrade or change package on a subscription system provisioned subscription.

Package change behaviours

While requesting a change, there are a few ways for us to determine what kind of change it is going to be.

Rank based (for upgrades/downgrades)

Introduced in Payway 4.5.3, packages can now be ranked in PAP. This means that the ranking of packages will be used instead of the payment period prices to decide whether it should be handled as an upgrade or downgrade (granted a ranking exists on both the source and target package). More on how Ranks work in Payway can be read upon here.

To use this behaviour, the default_behaviour parameter must be set to true.

Change request

Introduced in Payway 4.6.1, separate from package upgrades/downgrades, package changes can also be made. These work much in the same way as downgrades in the sense that they do not change the subscription of the customer until period end, but will be considered as a explicit package change instead of a upgrade/downgrade with all its implications.

To use this behaviour, the default_behaviour parameter must be set to false.


Environment URI


Identity Scope
No /external/subscription_system/w


Field Required Type Description
account_id Required String The customers account id owning the user product.
Size range: ..24
Allowed values: "/^[a-f\d]{24}$/i"
user_product_id Required String The current user product id (subscription id).
Size range: ..24
Allowed values: "/^[a-zA-Z-_0-9]+$/"
package_code Required String The package_code for the package in Payway that the subscription will change to.
Size range: ..50
Allowed values: "/^[a-zA-Z-_0-9]+$/"
target_period_id Required String The payment period id for the targeting package.
Size range: ..24
Allowed values: "/^[a-zA-Z-_0-9]+$/"
default_behaviour Optional Boolean Decides whether the package change should follow default behaviour or not. Read more about this parameter here.
Allowed values: true / false
Default: true

Curl Example

curl --request PUT \
  --url \
  --header 'accept: application/json' \
  --header 'authorization: Bearer token' \
  --header 'content-type: application/json' \
  --data '{
              "account_id": "56e1741a6fc9365306000001",
              "user_product_id": "56e1741a6fc9365306000002",
              "package_code": "adeprimo_digital",
              "target_period_id": "56e1741a6fc9365306000003",
              "default_behaviour": true


Field Description
id The id of the new user_product (if subscription is upgraded) or the current user_product (if subscription is downgraded or changing at the end of the period).

Example Response

HTTP 200 Updated
    "id": "50f3ac249f6aef294d000007"


This API uses the common error conventions of the Payway API

See common error responses