Change Future Invoice Details on Subscriptions

This scenarios will demonstrate how to update once off invoice details. 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 invoices 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


Did this page help you?