GET /receipts (v2)¶

Get a list of receipts.

Query parameters:

Name	Type	Description
`pretty`	boolean, optional, default: false	readable output formatting
`consumer`	string vector, optional, min: 1, max: 5	one or more consumer identifiers
`count`	integer, optional, min: 1, max: 20, default: 20	number of returned receipts
`id`	string vector, optional, min: 1, max: 20	one or more receipt identifiers
`store_id`	integer vector, optional, min: 1, max: 5	one or more store identifiers
`store_reference`	integer or string vector, optional, min: 1, max: 5	one or more store references
`transaction_id`	string vector, optional, min: 1, max: 20	one or more transaction identifiers
`newer`	string, optional	return receipts newer than this
`next`	string, optional	return the previous view of receipts newer than this
`prev`	string, optional	return the next view of receipts older than this

Example request:

This request will fetch up to 20 of the most recent receipts.

GET /receipts?consumer=1001 HTTP/1.1
Host: api.ereceipts.co.uk
ereceipts-api-version: 2
Accept: application/json

Example response:

This response contains a single receipt with a single item. See Receipt Object for a description of the format of the values in the receipts list.

HTTP/1.1 200 OK
Content-Length: 1624
Content-Type: application/json; charset=UTF-8

{
  "_links": {
    "latest": {
      "href": "https://api.staging.ereceipts.co.uk/receipts?consumer=1001"
    },
    "newer": {
      "href": "https://api.staging.ereceipts.co.uk/receipts?consumer=1001&newer=513e2391ee5e525ff9000000"
    }
  },
  "receipts": [
    {
      "id": "513e2391ee5e525ff9000000",
      "identifier": "1001",
      "incomplete": false,
      "items": [
        {
          "discounts": [],
          "name": "Cufflinks",
          "net": null,
          "properties": {
            "category": "Accessories"
          },
          "quantity": 1,
          "total": 10.0,
          "vat": {
            "amount": 0.0,
            "rate": 0.0
          }
        }
      ],
      "localtime": "2013-04-30T14:57:00+01:00",
      "net": null,
      "payments": [
        {
          "amount": 10.0,
          "method": "cash"
        }
      ],
      "pos_data_ids": [
        "52a877d0d535cf5070e84e34"
      ],
      "properties": {},
      "retailer": {
        "name": "Paperless Fashion",
        "vatno": null
      },
      "store": {
        "address": [
          "61 Hatton Garden"
        ],
        "city": "London",
        "country": "GBR",
        "name": "Paperless Fashion Clerkenwell",
        "phone": "+440000000000",
        "postcode": "EC1N 8LS",
        "properties": {}
      },
      "store_reference": "1",
      "till_uuid": "03b8fc59-cd41-4880-810c-543a34cc0528",
      "timestamp": "2013-04-30T13:57:00+00:00",
      "total": 10.0,
      "transaction_id": "0011120008",
      "vat": [
        {
          "amount": 0.0,
          "rate": 0.0
        }
      ]
    }
  ]
}

Pagination¶

The response contains links to support pagination in the _links key of returned object. Both pagination in terms of pages and infinite scroll is supported. Enumerating the number of available pages is not supported.

_links:

Name	Type	Description
`next`	mapping	link to the next page of receipts
`prev`	mapping	link to the previous page of receipts
`latest`	mapping	link to the most recent receipts
`newer`	mapping	link to newer receipts

Only the latest key is always present in the _links object. The other keys only appear when appropriate. The presence or absence of next and prev can be used to determine if more pages are available in either direction.

Multiple Pages¶

When implementing pagination in terms of distinct pages (e.g. with a next and previous page button) start by fetching the first page of receipts (i.e. GET the receipts resource with no arguments).

Use the links in _links to show the next and previous page links as appropriate:

If a next link is present, enable the next page button which, when clicked, performs a GET request to the next link. If no next link is present, disable the next page button.
If a prev link is present, enable the prev page button which, when clicked, performs a GET request to the prev link. If no prev link is present, disable the prev page button.
If a show latest receipts or show most recent receipts button is desired, performing a GET request using the latest link will retrieve the most recent receipts.
The newer link is not used for pagination when displaying pages of receipts.

The number of receipts returned per page is always that defined by the count query argument, except:

When there are less than count receipts available: only one page with less than count receipts will returned.
Where there are more than count receipts available: the last page will contain between one and count receipts, depending on the total number of receipts available.

It is possible that new receipts become available while paginating. When using the links in the _links object, no special handling is required to deal with this situation, since _links always reflects the current state at the time the request was made.

Infinite Scroll¶

When implementing infinite scroll, either with a manual or automatic loading of more receipts, make an initial request, fetching count most recent receipts (i.e. GET the receipts resource with no arguments).

You can use the links in _links to implement loading another page:

If a next link is present, more receipts can be loaded and added to the end of the infinite scroll view by making a GET request using the next link.

There are two options for refreshing the view with new receipts (i.e. those that have arrived after the initial request was made). A refresh would often, on a mobile device, be initiated using “pull to refresh”.

Simple Refresh¶

In this scenario when the user wants to refresh, the latest page of receipts is loaded and replaces all receipts that were previously loaded. This can be done by making a GET request to the latest link.

Load Newer Receipts Refresh¶

Unlike with the simple refresh, only receipts that are newer are loaded, and these can be added to the existing set of receipts that have already been retrieved. This is done using the newer link. Since the newer link only appears on the first page, it should be stored when the first page is loaded and used if the user refreshes the view.

When the user initiates the refresh operation:

Use the previously saved newer link in a GET request.
If the response does not contain any receipts, the refresh operation is complete.
If the response does contain receipts, add these to the top of the view, then:
- Inspect the _links.
- Save the newer link for later use.
- If a prev link is present, then there were more than count newer receipts and you can load these immediately by using the newer link back in step 1.
- If no prev link is present, the refresh operation is complete.