List queries

Most top level Billwerk+Optimize API resources have support for list operations where lists of entities can be fetched given different query attributes. The list operations share a common structure for requests and responses.

List queries are intended for specific queries, e.g. invoices for a specific customer and/or subscription, and infrequent on-demand operations to search for entities or to pull bulk data from Billwerk+Optimize. The list queries are not intended as a way to continously synchronize data in own system. This will be considered unfair API usage. Webhooks provide a way to keep data in own system in-sync with Billwerk+Optimize.

Requests

Requests are HTTP GET requests for the list operation on the specific resource. Query attributes are given as query parameters. All operations share this set of query parameters.

Parameter	Type	Description	Example
`range`	string	Optional range defining the date and time attribute used to limit the query and also defines the sorting. The sorting is always descending. Each resource offers different range attributes. Each resource have a default range if non is defined.	`range=created`
`from`	localdatetime	Optional time range start. The from time is inclusive. Given in local date (and maybe time) according to account timezone. Defaults to one month from `to` if no `interval` is given.	`from=2022-01-01`
`to`	localdatetime	Optional time range end. The to time is exclusive. Given in local date (and maybe time) according to account timezone. Defaults to now.	`to=2022-02-01`
`interval`	duration	Optional interval as an alternative to using `from`. The interval will be according to `to`, e.g. one week from `to`.	`interval=P1W`
`size`	integer	Optional page size between 10 and 100. Defaults to 20.	`size=100`
`next_page_token`	string	Used to get the next page if query results in multiple pages. Will be returned in response for current page. The above parameters must be the same in all subsequent page requsts.	`next_page_token=MTYzMjkxNDc4NTAwMDoxMA`

Notice that parameter values must be URL encoded when used in HTTP requests. E.g. from=2022-01-01T00:00:00 will be from=2022-01-01T00%3A00%3A00 when URL encoded.

Types

Request parameters are given in a number of types given below.

Type	Description	Example
localdatetime	Local date and optional time according to account timezone. Can be given in the following formats: `yyyy-MM-dd` `yyyyMMdd` `yyyy-MM-ddTHH:mm` `yyyy-MM-ddTHH:mm:ss` `yyyy-MM-ddTHH:mm:ss.SSS`	`to=2022-02-01T12:00:00.000`
duration	Duration in ISO 8601	`P1M` (one month)
stringlist	Some parameters can be lists. E.g. a list of entity states to filter on. Multiple values are defined by using the same parameter multiple times.	`state=authorized&state=settled`
integerinterval	Interval written as mathematical interval. `[` is from and including. `(` is from but excluding. `]` is to and including and `)` is to but excluding. If no value is defined there will be no limit on either the start or end.	`amount=[0;20000]` → `0<=amount<=20000` `amount=(0;20000]` → `0<amount<=20000` `amount=(0;20000)` → `0<amount<20000` `amount=(10000;)` → `10000<amount` `amount=[5000;5000]` → `amount=5000`
localdatetimeinterval	Same as integer interval except that values are in localdatetime	`dunning_success=[2022-01-01;2022-02-01)` dunning success in January 2022

Response

All list operations have the same generic response object.

{
    "size": 20,
    "count": 20,    
    "to": "2022-02-01T00:00:00.000",
    "from": "2022-01-01T00:00:00.000",
    "content": [ ... ],
    "range": "created",
    "next_page_token": "..."
}

Parameter	Type	Description
`size`	integer	Used page size
`count`	integer	Number of elements in current page. If less than page size it is the last page.
`to`	localdatetime	Local date and time range used as to (exclusive)
`from`	localdatetime	Local date and time range used as from (inclusive)
`content`	array	List of `count` entities for the page
`range`	string	Range attribute limited on
`next_page_token`	string	Pagination token to use to get the next page. If not present the last page has been reached.

Pagination

To get all pages of a list query, continue to use the same request parameters except for changing the next_page_token. Once a response has size=count or next_page_token is not returned, the last page has been reached.

Default range interval

The default range interval from to is one month if no specific from or interval is given. To search for all entities a long interval, e.g. interval=P100Y or from=1970-01-01, can be given.

There are exceptions to the default range interval though, if a relation like customer and/or subscription is used as a query attribute. That is, all entities related to another entity can be fetched without specifying a long interval as interval will default to infinity. E.g. all invoices for a customer can be fetched with speficying and interval. There is also an exception if an indexed attributed is used as query attribute. Currently this is limited to email on customer.

Query timeout

A list query can timeout and give error response with HTTP status 400 and code=144. In this case use a smaller time range for the operation. E.g. one month instead of three months.

Examples

Get list of invoices settled in January 2022:

GET https://api.reepay.com/v1/list/invoice?range=settled&from=2022-01-01&to=2022-02-01

Get list of invoices created the last three months with state pending or dunning:

GET https://api.reepay.com/v1/list/invoice?range=created&interval=P3M&state=pending&state=dunning

Searching and pagination

This section describes the legacy method to fetch lists. This functionality is deprecated and will be removed in the future. To fetch lists see the previous section on list queries.

Most top-level Billwerk+Optimize API resources have support for bulk fetches — "list" API methods. For instance you can list invoices, list customers, and list subscriptions. These list API methods share a common structure.

Billwerk+Optimize utilizes page-based pagination, using the query parameters page and size. Pass page to dictate what page you want to show and size to dictate how many items you want per page. Each individual resource will have resource specific filtering.

The generic response is either a page with total number and elements, or a slice lacking these two parameters. Slicing is used for optimization reasons when counting the total number of elements can be too expensive. The generic response contains the following parameters:

{
    "page": 50,
    "size": 50,
    "count": 50,
    "content": [ ... ],
    "total_elements": 500,
    "total_pages": 10,
    "search": "customer:cust0002"
}

Parameter	Type	Description
`page`	integer	Number of current page in paginated list
`size`	integer	Page size used
`count`	integer	Number of elements in current page
`content`	array	List of objects for current page
`total_elements`	integer	Total number of elements in paginated list (not included for sclices)
`total_pages`	integer	Total number of pages in paginated list (not included for sclices)
`search`	string	Optional used search expression (see below)

Example on the right.

For slicing a next page can be requested as long count = size.

Search expression

Most bulk fetches features an option to search. Searching is done using search expressions.
A search expression is as a comma separated list of search criteria. A search criteria is on the form:

<parameter_name><operator><value>

The following operators can be used:

Operator	Description
`:`	Equals. The parameter value must match `value`.
`;`	Contains. The `value` must be contained in the parameter value. For strings case-insensitivity comparison is used.
`<`	Lees than
`>`	Greater than

Example of a search expression for customers:

handle;cust,country:DK

The customer handle must contain cust and the country of the customer must equal DK.

For date and time parameters date and time must be given in ISO-8601. Example:

search=settled>2017-01-10T17:03:10+02:00

Notice that all values must be url encoded.