Associate New Plan to Subscription

Zion provides great tool to associate multiple plans to one subscription. This is very important use case when customer subscribes to more than one services from merchant system. Classic use cases are TV subscriptions where customer can have a monthly subscription plan of 300 Rs and chooses to subscribe sports pack during football world-cup for limited period. In such cases, merchant can update existing subscription with new plan which can run for limited period and then automatically stops.

HTTP method: PATCH

Path: {base_url}/api/sub/v1/merchant/subscriptions/{subscriptionId}

Request parameters

Header

ParameterDescription
X-PayU-_

_Subscription- Signature
mandatory
SHA512 Signature generated by encrypting request parameters in body by Merchant Key, Merchant Salt and Subscription Id.
merchantId
mandatory
Merchant Key received during onboarding.
Example: YQeVda

Generating X-PayU-Subscription-Signature

Signature = SHA512("merchantId:" + merchantId + "|subscriptionId:" + subscriptionId + "|" + merchantSalt)

Example

Signature = SHA512(merchantId:YQeVda|subscriptionId:5acb64a8070c9406b0928207|1v9b 1)

Sample request

For example, if there is a subscription ID 5c972a35652d405ed9834f52 which is having single plan id ZION155341061387133. Let’s see how we can associate another plan for the same subscription through PATCH interface. Before associating new plan, the subscriptionPlans object is similar to the followng:

{
  "subscriptionPlans": [
    {
      "planName": "Ultra HD",
      "startDate": "2019-03-30T11:00:00.000Z",
      "totalCount": 3,
      "billingInterval": 1,
      "billingCycle": "DAILY",
      "amount": {
        "value": 5,
        "currency": "INR"
      }
    }
  ]
}

Sample response

For the above sample request, the following response contains subscriptionPlans object is having two plans. The plan will be executed as follows:

  • Plan Id ZION155341061387133 will start on 2019-03-26. Since it’s a daily plan, it will result into charging customer for total 5 days, once per day and will stop on 2019-03-30
  • Plan Id ZION155343600151833 will start on 2019-03-30. It is also daily plan so will charge customer for 3 days once per day and will stop on 2019-04-01
{
  "subscriptionId": "5c972a35652d405ed9834f52",
  "createdDate": "2019-03-24T06:56:53.871Z",
  "modifiedDate": "2019-03-24T14:00:01.518Z",
  "subscriptionPlans": [
    {
      "planId": "ZION155341061387133",
      "startDate": "2019-03-26T11:00:00.000Z",
      "totalCount": 5,
      "numberOfPaidInvoices": 0,
      "numberOfInvoiceGenerated": 0,
      "status": "Active",
      "deleted": false,
      "nextBillingDates": "2019-03-26T11:00:00Z",
      "lastPaymentDates": null,
      "billingInterval": 1,
      "billingCycle": "DAILY",
      "planName": "Premium",
      "amount": {
        "value": 2,
        "currency": "INR"
      }
    },
    {
      "planId": "ZION155343600151833",
      "startDate": "2019-03-30T11:00:00.000Z",
      "totalCount": 3,
      "numberOfPaidInvoices": 0,
      "numberOfInvoiceGenerated": 0,
      "status": "Active",
      "deleted": false,
      "nextBillingDates": "2019-03-30T11:00:00Z",
      "lastPaymentDates": null,
      "billingInterval": 1,
      "billingCycle": "DAILY",
      "planName": "Ultra HD",
      "amount": {
        "value": 5,
        "currency": "INR"
      }
    }
  ],
  "authRefId": "10",
  "status": "Enabled",
  "subscriberEmail": "[email protected]",
  "subscriberMobile": "9999999999",
  "customParameter": {
    "Policynumber": "8885533311111",
    "Policytype": "Franklin Life"
  },
  "possibleActions": [
    {
      "action": "Fetch Subscription",
      "href": "{{base-url}}/api/sub/v1/subscription/5c972a35652d405ed9834f52",
      "httpMethod": "GET"
    },
    {
      "action": "Delete Subscription",
      "href": "{{base-url}}/api/sub/v1/subscription/5c972a35652d405ed9834f52",
      "httpMethod": "DELETE"
    }
  ]
}

HTTP status codes

The response body returned as a part of this API is same as that of Define Subscription API along with the following status codes getting returned.

HTTP Status CodeDescription
200Subscription updated successfully
403Forbidden request invalid Signature
400Request is malformed
404Merchant or Plan Id not found
422Request has invalid values
500Interval Server Error