Package Upgrade/Downgrade

Get detailed information about changing a subscriber’s package.

This API service allows you to change the current package of a subscriber.

Rules for Package Changes:

Whether the change is an upgrade or downgrade is defined by the changeType parameter sent in the request.

Downgrade

• If the new package is cheaper than the current one: → The change will take effect at the end of the current package period.

Upgrade

• If the new package is more expensive than the current one: → The unused portion of the current package will be credited towards the new package fee, → The subscriber will be switched to the new package immediately.

To ensure a smooth transition, the currency defined for the relevant country in the new package must match the currency in the current package. For example, if the current package uses USD for the USA, the new package must also use USD for the USA.

Method	POST
URL	https://api.zotlo.com/v1/payment/change-package
Request Parameters	newPackageId: The ID of the new package to be assigned. packageId: The ID of the current package associated with the subscription. subscriberIpAddress: The IP address of the subscriber. redirectUrl: If 3D Secure (3DS) is used during the transaction, this is the URL to which the user will be redirected after the payment is completed. You can use the URL of your Zotlo sales site here. subscriberId: The ID of the subscriber whose package will be changed. changeType: Accepts either upgrade or downgrade. If upgrade, the package will be upgraded and activated as soon as the new package fee is successfully charged to the credit card. If downgrade, the new package will be activated at the beginning of the next renewal period.

Example Request

When sending a request to the subscription inquiry service, you can obtain the necessary Access Key and Access Secret information from the Developer Tools/API Keys page in the Zotlo Panel.

POST https://api.zotlo.com/v1/payment/change-package HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
{
    "platform":"web",
    "subscriberId":"Z113322",
    "subscriberIpAddress":"212.154.57.216",
    "redirectUrl":"https://example.com",
    "changeType":"upgrade",
    "packageId":"zotlo.premium",
    "newPackageId":"zotlo.business"
}

Successful Response Examples

{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32ad6851343",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "7",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 12:55:23",
      "expireDate": "2020-09-10 14:38:34",
      "package": "zotlo-business",
      "country": "TR",
      "phoneNumber": "[phone]",
      "language": "tr",
      "originalTransactionId": "79448a13-b8bf-4b9e-9666-5dbabd8992c2",
      "cancellation": null,
      "customParameters": {
        "source": "Landing"
      }
    },
    "package": {
      "packageId": "zotlo-business",
      "price": 9.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Business"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "[e-mail]"
    },
    "newPackage": null,
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "response": {
      "isSuccess": true,
      "transactionId": "79448a13-b8bf-4b9e-9666-5dbabd8992c2",
      "providerTransactionId": "b4ee44dc-cbc0-400d-8f84-98688bdb7c80",
      "customTransactionId": "3e7f94f76e9748e2fefd3a8c28eda6ab",
      "statusCode": "S0000001",
      "statusMessage": "Ödeme işlemi başarıyla tamamlandı.",
      "paymentDate": "2020-08-11 02:38:34",
      "providerStatus": null,
      "paymentStatus": "COMPLETE",
      "redirectUrl": null,
      "paymentProvider": creditCard"
    },
    "redirect": null,
    "paymentStatus": "COMPLETE",
    "paymentHash": "207851900cae72c17d80a17ea65879f321718055"
  }
}

Successful Response Parameters

The parameters included in the successful response are as follows.

Alan	Açıklama
newPackage	Returns the details of the new package to be assigned. If there is a price difference between the current and new packages, the change will only be applied after the payment is successfully processed.

Failed Response Example

Our services return HTTP status code 200 for successful responses. For unsuccessful cases, HTTP status codes 400 or 500 are returned. An example error response is as follows:

{
  "meta": {
    "requestId": "MacBook-Pro.local-REQ-5e7da75228368",
    "httpStatus": 400,
    "errorMessage": "Kullanıcı abonelik profili bulunamadı.",
    "errorCode": 400009
  },
  "result": []
}

Failed Response Parameters

Below are the parameters included in failed responses.

Parameter	Description
requestId	It is the unique request parameter generated and stored by Zotlo for your transaction.
httpStatus	It is the HTTP status code related to the response. The standard codes 400 or 500 are returned.
errorMessage	It is the detail of the received error. The error message is provided in the language specific to the parameter you sent.
errorCode	It is the error code from Zotlo.
result	The values this field can take are variable.If there’s an error, it will include data; otherwise, it will return as an empty object.