Change product

/accounts/change_product

Target audience: Developers

Release version: 4.6.1

Change product¶

Introduction¶

This endpoint lets you request a package change on an ongoing subscription. There are a number of requirements to take into account when using this functionality, which you can read more about here.

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.

Price based (for upgrades/downgrades)¶

Package changes/requests will typically be performed as either an upgrade or a downgrade. By default, this decision will be based upon the payment period prices. If the customer would land on a more expensive period, we'll see it as an upgrade. If the customer would land on a cheaper period, we'll see it as a downgrade.

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

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, and a target_period_id must be specified.

URI¶

Environment	URI
Stage	https://payway-api.stage.adeprimo.se/external/api/v1/accounts/change_product
Production	https://backend.worldoftulo.com/external/api/v1/accounts/change_product

Requirements¶

Identity	Scope
Yes	`/external/account/w`

Parameters¶

Field	Required	Type	Description
account_id	Optional	String	The id of the account to change product on. Size range: ..24 Allowed values: "/^[a-f\d]{24}$/i"
user_product_id	Optional	String	The id of the user product to change product on. Size range: ..24 Allowed values: "/^[a-f\d]{24}$/i"
package_code	Optional	String	The package_code of the package to upgrade/downgrade into. Size range: 1..50
target_period_id	Optional	String	The id of the period to transition to. If none is specified, we will attempt to find one based on the current payment method and a period length of 1 month. Size range: ..24 Allowed values: "/^[a-f\d]{24}$/i" Release version 4.4.9
default_behaviour	Optional	Boolean	Decides whether the package change should follow default behaviour or not. Read more about this parameter here. Default: True
traffic_source	Optional	String	The traffic source that should be applied on the new order. Size range: ..128
merchant_reference	Optional	String	The merchant reference that should be applied on the new order.

Curl Example¶

curl --request PUT \
  --url https://payway-api.stage.adeprimo.se/external/api/v1/accounts/change_product \
  --header 'accept: application/json' \
  --header 'authorization: Bearer token' \
  --header 'content-type: application/json' \
  --data '{
              "account_id": "a09df3af890dj9df8ad9f8ja",
              "user_product_id": "50f3ac249f6aef294d000007",
              "package_code": "adeprimo_premium_extra_large",
              "target_period_id": "37f3ac249f6aef294d337357"
          }'

Response¶

Field	Description
id	The id of the new user product.

HTTP 200 Updated
{
    "id": "50f3ac249f6aef294d000007"
}

Errors¶

This API uses the common error conventions of the Payway API

See common error responses