Modifying invoice streams

You can apply overrides to invoice streams for both policy-level and account-level billing. Invoice stream overrides affect planned invoices only.

Use the following endpoint to set overrides on invoice streams:

PATCH /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}

Using this endpoint, you can set the following four fields:

Description - The description
overridingPaymentInstrument - The payment instrument to use instead of the account-level payment instrument
overridingLeadTimeDayCount - The lead time instead of the one defined by the account's billing plan
overridingBillDateOrDueDateBilling - The invoicing model to use instead of the model specified at the account level (either due date billing or bill date billing)

To modify the invoice days, a different endpoint is used. For more information, see ~Modifying invoice days.

The following example demonstrates updating the description, payment instrument, lead time, and invoicing model for an account-level invoice stream.

Command

PATCH /billing/v1/accounts/bc:Sy1Fmx9EDhH-P-o5rRzum/invoice-streams/bc:STmESSufleiqIALtu13ys

Request body

{
    "data": {
        "attributes": {
            "description": "Weekly invoice stream with overrides",
            "overridingBillDateOrDueDateBilling": {
                "code": "DueDateBilling"
            },
            "overridingLeadTimeDayCount": 14,
            "overridingPaymentInstrument": {
                "id": "bc:SV2tI8sg4BapKqRCGKFBe"
            }
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "creationOrder": 1,
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "description": "Weekly invoice stream with overrides",
            "displayName": "Every Week",
            "id": "bc:STmESSufleiqIALtu13ys",
            "overridingBillDateOrDueDateBilling": {
                "code": "DueDateBilling",
                "name": "Due Date"
            },
            "overridingLeadTimeDayCount": 14,
            "overridingPaymentInstrument": {
                "displayName": "Cash",
                "id": "bc:SV2tI8sg4BapKqRCGKFBe",
                "type": "UniversalPaymentInstrument",
                "uri": "/billing/v1/universal-payment-instruments/bc:SV2tI8sg4BapKqRCGKFBe"
            },
            "periodicity": {
                "code": "everyweek",
                "name": "Every Week"
            },
            "unappliedFund": {
                "displayName": "Custom Unapplied",
                "id": "bc:Sl3lIAkj2g4wfBjEoAKCu",
                "type": "UnappliedFund",
                "uri": "/billing/v1/accounts/bc:Sy1Fmx9EDhH-P-o5rRzum/unapplied-funds/bc:Sl3lIAkj2g4wfBjEoAKCu"
            }
        },
     ...
    }
}

Remove overrides

To undo a specific override, send a request payload with a null value for the desired field. For example, the following undoes overrides on payment instruments and lead time:

{
    "data": {
        "attributes": {
            "overridingPaymentInstrument": null,
            "overridingLeadTimeDayCount": null
        }
    }
}

Modifying invoice days

Invoice days can be modified on both policy-level and account-level invoice streams.

Update the invoice days for an invoice stream using the following endpoint:

POST /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}/update-invoice-days

To update invoice days, you must know the periodicity of the invoice stream. This is contained in the invoice stream object.

The possible invoice days vary depending on the periodicity of the invoice stream.

For a weekly invoice stream, the invoice day is a day of the week, such as Monday.
For an every-other-week invoice stream, the invoice day is calculated based on 14-day increments from a single anchor date.
For a twice-per-month invoice stream, there are two days of the month as the invoice days.
For a monthly invoice stream, the invoice day is a day of the month.

The following table details what fields to include to override invoice days for different periodicities.


Invoice stream periodicity code	Field to include	Data type	Notes
`everyweek`	`overridingDayOfWeek`	Typekey reference to the `DayOfWeek` typelist
`everyotherweek`	`overridingAnchorDate`	String (in the format YYYY-MM-DD)	For example, a date of 2024-03-04 would invoice every two weeks beginning on that day. So the second invoice would occur on 2024-18-2024, the third on 2024-04-01, and so on.
`twicepermonth`	`overridingFirstInvoiceDayOfMonth`, `overridingSecondInvoiceDayOfMonth`	Integer	Both values must be set when overriding invoice days or nullifying overrides. Integer cannot exceed 31. If set to 31, defaults to the last day of the month for months with fewer than 31 days.
`monthly`	`overridingFirstInvoiceDayOfMonth`	Integer	Integer cannot exceed 31. If set to 31, defaults to the last day of the month for months with fewer than 31 days.

Examples of updating invoice days

The following example demonstrates changing the invoice day on an invoice stream with a twice-per-month periodicity. This example causes invoices to occur on the 7th and 21st of each month.

Command

/billing/v1/accounts/bc:Sy1Fmx9EDhH-P-o5rRzum/invoice-streams/bc:SxGrQZ1FPUKF-Md5vpgY0/update-invoice-days

Request body

{
    "data": {
        "attributes": {
            "overridingFirstInvoiceDayOfMonth": 7,
            "overridingSecondInvoiceDayOfMonth": 21
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "creationOrder": 1,
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "displayName": "Twice Per Month",
            "id": "bc:SxGrQZ1FPUKF-Md5vpgY0",
            "overridingFirstAnchorDate": "2010-01-07",
            "overridingSecondAnchorDate": "2010-01-21",
            "periodicity": {
                "code": "twicepermonth",
                "name": "Twice Per Month"
            },
            "unappliedFund": {
                "displayName": "Custom Unapplied-3",
                "id": "bc:S5PMcB2rAFnKYvsbnK49V",
                "type": "UnappliedFund",
                "uri": "/billing/v1/accounts/bc:Sy1Fmx9EDhH-P-o5rRzum/unapplied-funds/bc:S5PMcB2rAFnKYvsbnK49V"
            }
        }
    }
}

As another example, for an invoice stream with a weekly periodicity, the request body would have the following format:

{
    "data": {
        "attributes": {
            "overridingDayOfWeek": {
	            "code": "monday"
            }
        }
    }
}

Remove overrides

To undo overrides, send a request payload with a null value for the desired field. For example, the following removes an override on the day of the week:

{
    "data": {
        "attributes": {
            "overridingDayOfWeek": null
        }
    }
}