Billing schedules

A billing schedule describing the schedule for billing a service user, service user contact of location contact.

Billing schedules can either relate to a single contact (e.g service user, service user contact or location contact) or they can be shared allowing them to be assigned to any contact.

The billing schedule object

Attributes

  • _id
    string

    A unique Id for the billing schedule.

  • archived
    boolean

    Flag indiciating if the billing schedule has been archived.

  • billing_date_offset_rule
    string

    The rule used to calculate the billing date offset from the start/end of a billing period for the schedule; day_of_month, days_from_billing_period.

  • billing_date_offset_unit
    integer

    The number of days or a given day of the month that the billing date is offset for the schedule from the start/end of the billing period.

  • billing_period_day
    integer

    The day of the month (1-28) that a monthly billing period starts from.

  • billing_period_length
    integer

    If the billing rules is set as weeks or days then the length refers to the number of weeks or days the billing period spans for the schedule.

  • billing_period_rule
    string

    The rule used to calculate the billing period for the schedule; monthly, weeks, weeks_445, days.

  • billing_period_start_date
    string

    The date on which billing starts for the schedule.

  • billing_process
    string

    Whether the schedule is billed in advance or in-arrears; in_advance, in_arrears, mid_period.

  • created
    string

    The date/time the billing schedule was created.

  • invoices_due_rule
    string

    The rule for determining when an invoice will fall due for the schedule;day_current_month, day_following_month, days_after_invoice_date, days_after_invoice_month.

  • invoices_due_unit
    integer

    The day or number of days from the date of invoice after which an invoice for a billing contract for the schedule is due.

  • location_contact
    string

    The location contact the billing schedule relates to.

  • modified
    string

    The date/time the billing schedule was modified.

  • name
    string

    A name assigned to the billing schedule to make it easier to identify. Shared billing schedules cannot share the same name, dedicated billing schedules can share names provided they are not for the same contact.

  • service_user
    string

    The service user the billing schedule relates to.

  • service_user_contact
    string

    The service user contact the billing schedule relates to.

  • shared
    boolean

    Flag indiciating if the billing schedule is shared as opposed to specific to a billing party.

The billing schedule object
{
    "_id": "66bfb4d09ab4e3d6eb735f0e",
    "archived": false,
    "billing_date_offset_rule": "days_from_billing_period",
    "billing_date_offset_unit": 0,
    "billing_period_day": 1,
    "billing_period_length": null,
    "billing_period_rule": "monthly",
    "billing_period_start_date": "2021-07-17",
    "billing_process": "in_advance",
    "created": "2024-08-16 20:21:36",
    "invoices_due_rule": "days_after_invoice_date",
    "invoices_due_unit": 30,
    "location_contact": null,
    "modified": "2024-08-16 20:21:36",
    "name": "Private (monthly)",
    "service_user": null,
    "service_user_contact": null,
    "shared": true
}

List all billing schedules

Return a list of billing schedules.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-archived
    optional
    default no

    A filter that allows schedules that are currently archived to be included or excluded.

    • unset
    • yes
    • no
  • filters-ids
    optional

    A filter that accepts a list of Ids and filters the items returned to those with an Id in the list.

  • filters-location_contact
    optional

    A filter that accepts a list of location contact Ids and filters billing schedules to those where the billing party is one of the location contacts.

  • filters-modified_after
    optional

    A filter that accepts a date/time and filters the items returned to those modified after the date/time.

  • filters-modified_before
    optional

    A filter that accepts a date/time and filters the items returned to those modified before the date/time.

  • filters-q
    optional

    A case insensitive keyword filter applied to the following fields; name.

  • filters-service_user
    optional

    A filter that accepts a list of service user Ids and filters billing schedules by the service user they are for.

  • filters-service_user_contact
    optional

    A filter that accepts a list of service user contact Ids and filters billing schedules to those where the billing party is one of the service user contacts.

  • filters-shared
    optional
    default unset

    A filter that allows billing schedules to be filtered by whether the schedule is shared or specific to a billing party.

    • unset
    • yes
    • no
  • page
    optional
    default 1

    The page number to fetch.

  • per_page
    optional
    default 10

    The number of items to return per page.

  • sort_by
    optional
    default _id

    A list of fields the returned items can be sorted by. Fields prefixed with minus (-) sign are sorted in descending order.

    • _id
    • created
    • billing_period_start_date
    • modified

Response

Returns a page of billing schedules.

GET
/v1/billing-schedules
var billingSchedules = apiClient.Request(
    HttpMethod.Get,
    "billing-schedules",
    new MultiValueDict()
        .Add("attributes", "name", "billing_period_start_date")
        .Add("filters-shared", "yes")
);
<?php

$billing_schedules = $api_client->request(
    'GET',
    'billing-schedules',
    [
        'attributes'=>['name', 'billing_period_start_date'],
        'filters-shared'=>'yes'
    ]
);
billing_schedules = api_client(
    'GET',
    'billing-schedules',
    params={
        'attributes': ['name', 'billing_period_start_date'],
        'filters-shared': 'yes'
    }
)
billing_schedules = api_client.request(
    'GET',
    'billing-schedules',
    params: {
        'attributes' => ['name', 'billing_period_start_date'],
        'filters-shared' => 'yes'
    }
)
Response
{
    "item_count": 2,
    "items": [
        {
            "_id": "66bfb4d09ab4e3d6eb735f0e",
            "billing_period_start_date": "2021-07-17",
            "name": "Private (monthly)"
        },
        {
            "_id": "66bfb4d09ab4e3d6eb735f10",
            "billing_period_start_date": "2021-07-17",
            "name": "Private (monthly) DirectDebit"
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve a billing schedule

Retrieve a billing schedule object.

Response

Returns a billing schedule object.

GET
/v1/billing-schedules/<billing_schedule_id>
var billingSchedule = apiClient.Request(
    HttpMethod.Get,
    $"billing-schedules/{billingScheduleId}"
);
<?php

$billing_schedule = $api_client->request(
    'GET',
    'billing-schedules/' . $billing_schedule_id
);
billing_schedule = api_client(
    'GET',
    f'billing-schedules/{billing_schedule_id}'
)
billing_schedule = api_client.request(
    'GET',
    "billing-schedules/#{billing_schedule_id}"
)
Response
{
    "_id": "66bfb4d09ab4e3d6eb735f0e",
    "archived": false,
    "billing_date_offset_rule": "days_from_billing_period",
    "billing_date_offset_unit": 0,
    "billing_period_day": 1,
    "billing_period_length": null,
    "billing_period_rule": "monthly",
    "billing_period_start_date": "2021-07-17",
    "billing_process": "in_advance",
    "created": "2024-08-16 20:21:36",
    "invoices_due_rule": "days_after_invoice_date",
    "invoices_due_unit": 30,
    "location_contact": null,
    "modified": "2024-08-16 20:21:36",
    "name": "Private (monthly)",
    "service_user": null,
    "service_user_contact": null,
    "shared": true
}