Change Future Invoice Details (subscription model)

This scenarios will cover integrations need to update a once/off invoice detail. This can be done using the Future Invoice API.

How to Retrieve the List of Future Invoice

There are 3 scenario when a future invoice is updated:
a) Update Once/Off future invoice details
b) Delete a future invoice.
c) Mark that future invoice as collected (Through the counter).

🚧

NOTE

Future invoice s are considered as virtual invoice in Ezypay. This means that there will not be an invoice id generated until the actual day of the billing.

[GET] https://api-sandbox.ezypay.com/v2/billing/futureinvoices?subscriptionId={{subscriptionId}}&customerId={{customerId}}&from={{from}}&until={{until}}&limit={{limit}}

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

{
    "data": [
        {
            "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
            "date": "2019-06-21",
            "cycleStartDate": "2019-06-21",
            "cycleEndDate": null,
            "items": [
                {
                    "description": "Test Subscription 001",
                    "amount": {
                        "currency": "AUD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "subscription_payment",
                    "accountingCode": "ABC123_NSW"
                },
                {
                    "description": "Transaction Fee",
                    "amount": {
                        "currency": "AUD",
                        "value": 2.98,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "transaction_fee",
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "AUD",
                "value": 202.98,
                "type": null
            },
            "totalTax": {
                "currency": "AUD",
                "value": 18.45,
                "type": null
            }
        },
        {
            "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
            "date": "2019-07-05",
            "cycleStartDate": "2019-07-05",
            "cycleEndDate": "2019-07-18",
            "items": [
                {
                    "description": "Test Subscription 001",
                    "amount": {
                        "currency": "AUD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "subscription_payment",
                    "accountingCode": "ABC123_NSW"
                },
                {
                    "description": "Transaction Fee",
                    "amount": {
                        "currency": "AUD",
                        "value": 2.98,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "transaction_fee",
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "AUD",
                "value": 202.98,
                "type": null
            },
            "totalTax": {
                "currency": "AUD",
                "value": 18.45,
                "type": null
            }
        },
        {
            "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
            "date": "2019-07-19",
            "cycleStartDate": "2019-07-19",
            "cycleEndDate": "2019-08-01",
            "items": [
                {
                    "description": "Test Subscription 001",
                    "amount": {
                        "currency": "AUD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "subscription_payment",
                    "accountingCode": "ABC123_NSW"
                },
                {
                    "description": "Transaction Fee",
                    "amount": {
                        "currency": "AUD",
                        "value": 2.98,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "transaction_fee",
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "AUD",
                "value": 202.98,
                "type": null
            },
            "totalTax": {
                "currency": "AUD",
                "value": 18.45,
                "type": null
            }
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 37
    }
}

a. Update Once/Off future invoice details

For this example the Subscription Id: 7bcbbefb-66ce-47f8-83b8-ddedaf4ad706 and the Cycle Start Date: 2019-06-21 will be used.

The amount will be updated to AUD 250.

🚧

NOTE:

"SubscriptionId" and the "cycleStartDate" will be the information needed from the Get List of Future Invoice API call.

API Document Endpoint: https://developer.ezypay.com/reference#update-a-future-invoice

{
        "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
            "date": "2019-06-21",
            "cycleStartDate": "2019-06-21",
            "cycleEndDate": null,
            "items": [
                {
                    "description": "Test Subscription 001",
                    "amount": {
                        "currency": "AUD",
                        "value": 250,
                        "type": null
                    },
                    "tax": {
                        "rate": 10
                    },
                    "type": "subscription_payment",
                    "accountingCode": "ABC123_NSW"
                }]
}
{
    "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
    "date": "2019-06-21",
    "cycleStartDate": "2019-06-21",
    "cycleEndDate": null,
    "items": [
        {
            "description": "Test Subscription 001",
            "amount": {
                "currency": "AUD",
                "value": 250,
                "type": null
            },
            "tax": {
                "rate": 10
            },
            "type": "subscription_payment",
            "accountingCode": "ABC123_NSW"
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 250,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 22.73,
        "type": null
    }
}

b. Cancel A Future Invoice

[DELETE] https://api-sandbox.ezypay.com/v2/billing/futureinvoices?subscriptionId={{SubscriptionId}}&cycleStartDate={{cycleStartDate}}

Will be using the one modified above and remove it:
Subscription Id: 7bcbbefb-66ce-47f8-83b8-ddedaf4ad706
CycleStartDate: 2019-06-21

{
    "entityId": "8392277e-4ae0-485e-98b2-71820f651bd0",
    "deleted": true
}

API Document Endpoint: https://developer.ezypay.com/reference#delete-a-future-invoice

c. Mark that future invoice as collected (Through the counter).

[POST] https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment

The second invoice from the subscription will be marked as collected using "Cash"
Subscription Id: 7bcbbefb-66ce-47f8-83b8-ddedaf4ad706
Cycle Start Date: 2019-07-05
Payment Method Type: "CASH"

{
    "subscriptionId":"7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
    "cycleStartDate":"2019-07-05",
    "paymentMethodType": "cash"
}
{
    "id": "3bbd83bd-e9ea-4cd2-bac7-0c76895e01ec",
    "documentNumber": "IN0000000000000237",
    "date": "2019-06-18",
    "dueDate": "2019-07-05",
    "scheduledPaymentDate": null,
    "status": "PAID",
    "memo": "AIF TEST",
    "items": [
        {
            "description": "Test Subscription 001",
            "amount": {
                "currency": "AUD",
                "value": 200,
                "type": null
            },
            "tax": {
                "rate": 10
            },
            "id": "35db50bc-ebd8-408a-9d5d-e0af2c2dea0a",
            "type": "subscription_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0,
                "type": null
            },
            "accountingCode": "ABC123_NSW"
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 200,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 200,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 18.18,
        "type": null
    },
    "customerId": "aaf40599-0fbc-44d3-8902-55365c6de9e5",
    "subscriptionId": "7bcbbefb-66ce-47f8-83b8-ddedaf4ad706",
    "subscriptionName": "Test Subscription 001",
    "paymentMethodToken": null,
    "autoPayment": false,
    "createdOn": "2019-06-18T16:20:37.410"
}

API Document Endpoint: https://developer.ezypay.com/reference#record-an-external-payment-for-a-future-invoice