Change Subscription Details

Change Subscription Details is used when a customer wants to change a TAC amount (Total Amount to be Collected) on an existing customer subscription. Below are the steps required to perform this:

Get the current customer subscription (Step 1). This will provide the needed details to allow an integrator to create a edit subscription form.
Update the common fields like Total Amount Collected (TAC) or even change the re-occurring amount previously set.
When the update button is clicked on the integrator's Application, the cancel subscription (Step 2) will be used and a new subscription (Step 3) with the newly modified parameters will be used.

❗️
Integrators will need to cancel the current subscription and create a new subscription if the customer needs to change any details in a customer subscription.

Step 1: Get Current Subscription

[GET] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions/{{SubscriptionId}}

{
    "id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
    "customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
    "planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
    "name": "Test8 Payment Plan",
    "status": "ACTIVE",
    "startDate": "2019-05-27",
    "endDate": "2021-05-01",
    "paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
    "accountingCode": "ABC123_NSW",
    "amount": {
        "currency": "AUD",
        "value": 100,
        "type": null
    },
    "tax": {
        "rate": 10
    },
    "nextBillingDate": "2019-07-01",
    "nextFutureInvoice": {
        "subscriptionId": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
        "date": "2019-07-01",
        "cycleStartDate": "2019-07-01",
        "cycleEndDate": "2019-07-31",
        "items": [
            {
                "description": "Test8 Payment Plan",
                "amount": {
                    "currency": "AUD",
                    "value": 100,
                    "type": null
                },
                "tax": {
                    "rate": 10
                },
                "type": "subscription_payment",
                "accountingCode": "ABC123_NSW"
            },
            {
                "description": "Transaction Fee",
                "amount": {
                    "currency": "AUD",
                    "value": 1.49,
                    "type": null
                },
                "tax": {
                    "rate": 10
                },
                "type": "transaction_fee",
                "accountingCode": null
            }
        ],
        "amount": {
            "currency": "AUD",
            "value": 101.49,
            "type": null
        },
        "totalTax": {
            "currency": "AUD",
            "value": 9.23,
            "type": null
        }
    },
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "AUD",
        "value": 1000,
        "type": null
    },
    "totalBillingCycles": 1,
    "remainingToPay": {
        "currency": "AUD",
        "value": 4000,
        "type": null
    },
    "remainingBillingCycles": null,
    "endTargetAmount": {
        "currency": "AUD",
        "value": 5000,
        "type": null
    },
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-05-27T06:41:20.211",
    "autoPayment": true,
    "setupPayments": null
}

API Document Endpoint: https://developer.ezypay.com/reference#list-subscriptions

📘
NOTE
There will be 2 parts when a change of subscription details is required. The example on Step 2 and Step 3 will be based on a change to the TAC (Total Amount Collected) amount.

Step 2: Cancel Previous Subscription

[PUT] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions/{{SubscriptionId}}/cancel

{}

{
    "id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
    "customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
    "planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
    "name": "Test8 Payment Plan",
    "status": "CANCELLED",
    "startDate": "2019-05-27",
    "endDate": "2021-05-01",
    "paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
    "accountingCode": "ABC123_NSW",
    "amount": {
        "currency": "AUD",
        "value": 100,
        "type": null
    },
    "tax": {
        "rate": 10
    },
    "nextBillingDate": null,
    "nextFutureInvoice": null,
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "AUD",
        "value": 1000,
        "type": null
    },
    "totalBillingCycles": 1,
    "remainingToPay": {
        "currency": "AUD",
        "value": 4000,
        "type": null
    },
    "remainingBillingCycles": null,
    "endTargetAmount": {
        "currency": "AUD",
        "value": 5000,
        "type": null
    },
    "endTargetBillingCycles": null,
    "cancelledDate": "2019-05-28",
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-05-27T06:41:20.211",
    "autoPayment": true,
    "setupPayments": null
}

📘
NOTE:
The [GET] Subscription would have to allow the needed subscription details to be displayed on the Integrator's Subscription Form. This would allow the merchant to update the TAC amount and click on the update button (which would work as a cancel and create a new transaction).
For this scenario, the TAC amount will be updated from AUD 4000 to AUD 4500 while keeping the all other configuration to be the same.
There will be an update to this API soon, that will allow integrators to update the future billing end date for the customer subscription details.

Step 3: Create A New Subscription

[POST] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions

{
  "name": "Test8 Payment Plan (Updated)",
  "customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
  "planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
  "autoPayment": "true",
  "customerEmailNotification": "true",
  "markAsPending": "false",
  "billingStart": "immediate",
  "startDate": "2019-06-01",
  "intervalUnit": "MONTH",
  "interval": 1,
  "accountingCode": "ABC123_NSW",
  "billingEnd": "amount_collected",
  "billingEndValue": 4500
}

{
    "id": "43f2614f-83e4-4fa3-a7ca-2d854c4bbebb",
    "customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
    "planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
    "name": "Test8 Payment Plan (Updated)",
    "status": "FUTURE",
    "startDate": "2019-06-01",
    "endDate": "2021-05-01",
    "paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
    "accountingCode": "ABC123_NSW",
    "amount": {
        "currency": "AUD",
        "value": 100,
        "type": null
    },
    "tax": {
        "rate": 10
    },
    "nextBillingDate": "2019-06-01",
    "nextFutureInvoice": {
        "subscriptionId": "43f2614f-83e4-4fa3-a7ca-2d854c4bbebb",
        "date": "2019-06-01",
        "cycleStartDate": "2019-06-01",
        "cycleEndDate": null,
        "items": [
            {
                "description": "Test8 Payment Plan (Updated)",
                "amount": {
                    "currency": "AUD",
                    "value": 100,
                    "type": null
                },
                "tax": {
                    "rate": 10
                },
                "type": "subscription_payment",
                "accountingCode": "ABC123_NSW"
            },
            {
                "description": "Transaction Fee",
                "amount": {
                    "currency": "AUD",
                    "value": 1.49,
                    "type": null
                },
                "tax": {
                    "rate": 10
                },
                "type": "transaction_fee",
                "accountingCode": null
            }
        ],
        "amount": {
            "currency": "AUD",
            "value": 101.49,
            "type": null
        },
        "totalTax": {
            "currency": "AUD",
            "value": 9.23,
            "type": null
        }
    },
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalBillingCycles": 0,
    "remainingToPay": {
        "currency": "AUD",
        "value": 4500,
        "type": null
    },
    "remainingBillingCycles": null,
    "endTargetAmount": {
        "currency": "AUD",
        "value": 4500,
        "type": null
    },
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-05-28T02:58:24.918",
    "autoPayment": true,
    "setupPayments": null
}

📘
NOTE
Some key items are important when a change of details to the subscription model is required.

Startdate => The start date is very important if it is not a future start date.

MarkAsPending => This would be false as most of the time a change to a subscription plan would want to be initiated instantly.

BillingEnd => The value will need to be changed as this is a scenario where the TAC is changed for a customer subscription.

BillingEndValue => New value that will be the new TAC (use the [GET] Subscription to check on how much is still remaining).

API Document Endpoint: https://developer.ezypay.com/reference#create-a-subscription

Change Subscription Details

❗️

Step 1: Get Current Subscription

📘
NOTE

Step 2: Cancel Previous Subscription

📘
NOTE:

Step 3: Create A New Subscription

📘
NOTE

❗️

Step 1: Get Current Subscription

📘NOTE

Step 2: Cancel Previous Subscription

📘NOTE:

Step 3: Create A New Subscription

📘NOTE

📘
NOTE

📘
NOTE:

📘
NOTE