POST /receipts¶

Post a single receipt.

Body parameters:

Name	Type	Description
`items`	array of Item Objects, required, min: 1	see Item Object
`identifier`	string, optional	retailer-specific consumer identifier (loyalty card number, e-mail address or other)
`properties`	Receipt Properties Object, optional	see Receipt Properties Object
`transaction_id`	string, required	retailer-specific, unique transaction identifier
`localtime`	string, required, date and time (timezone optional) using ISO 8601	the date and time on the receipt, optionally including the timezone offset in which the receipt was generated (the receipt, store, or retailer timezone is used if a timezone offset is not included) formatted as an ISO 8601 date and time
`payments`	array of Payment Objects, optional	see Payment Object
`total`	float, required	the total price on the receipt
`subtotal`	float, optional	the subtotal on the receipt
`gross`	float, optional	the gross price
`net`	float, optional	the net price
`vat`	array of VAT Objects, optional	deprecated: use `taxes` instead
`taxes`	array of Tax Objects, optional	see Tax Object
`discounts`	array of Discount Objects, optional	see Discount Object
`store_reference`	integer or string, required	the store identifier
`store`	Store Object, optional	see Store Object. Should only be set when store creation/update from receipts has been enabled, otherwise the field will be ignored.
`l10n`	L10N Object, optional	see L10N Object
`incomplete`	boolean, optional, default: false	signifies missing fields on the receipt
`duplicate`	boolean, optional, default: false	signifies that this receipt is a duplicate - for details, see Duplicate Receipts
`external_id`	string, optional	a UUIDv4, as defined in RFC 4122
`attachments`	mapping of labels to Attachments, optional	see Attachment Object

Example request:

POST /receipts HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json
Content-Length: 387
Content-Type: application/json

{
  "identifier": "990000000001",
  "items": [
    {
      "name": "Cufflinks",
      "quantity": 1,
      "total": 10.0,
      "vat": {
        "amount": 0.0,
        "rate": 0.0
      }
    }
  ],
  "localtime": "2013-04-30T14:57:00+01:00",
  "store_reference": "1",
  "total": 10.0,
  "transaction_id": "0011120008",
  "vat": [
    {
      "amount": 0.0,
      "rate": 0.0
    }
  ]
}

Example response:

The response contains the unique receipt identifier, which can be used in subsequent operations, e.g. GET /receipts/{id}.

HTTP/1.1 201 Created
Content-Length: 34
Content-Type: application/json; charset=UTF-8
Location: https://api.ereceipts.co.uk/receipts/513e2391ee5e525ff9000000

{"id": "513e2391ee5e525ff9000000"}

Links are not present in the response by default but can be configured on demand to include:

a URL of an HTML rendering (webview) of the receipt,

a URL of a PDF rendering of the receipt,

a URL of a QR code image containing the webview URL.

HTTP/1.1 201 Created
Content-Length: 376
Content-Type: application/json; charset=UTF-8
Location: https://api.ereceipts.co.uk/receipts/513e2391ee5e525ff9000000

{
  "id": "513e2391ee5e525ff9000000",
  "_links": {
    "webview": {
      "href": "https://webview.ereceipts.co.uk/513e2391ee5e525ff9000000",
      "qrcode": "https://barcodes.ereceipts.co.uk/qrcode?c=https%3A%2F%2Fwebview.ereceipts.co.uk%2F513e2391ee5e525ff9000000"
    },
    "pdf": {
      "href": "https://webview.ereceipts.co.uk/pdf/513e2391ee5e525ff9000000"
    }
  }
}

Alternatives¶

Some fields, such as the name field in the Item Object, may have alternatives. Fields that support alternatives are clearly marked in the documentation. The general format of such a field is: field_name:alternative_name. Attempting to submit an alternative for a field which does not support alternatives, will cause a schema validation error and the submission of the receipt to fail. Additionally, using an invalid or incorrectly formatted alternative name will cause the submission to fail with a schema validation error.

Example of submitting a receipt with alternatives:

POST /receipts HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json
Content-Length: 396
Content-Type: application/json

{
  "identifier": "990000000001",
  "items": [
    {
      "name": "Ice cream",
      "name:el": "\u03c0\u03b1\u03b3\u03c9\u03c4\u03cc",
      "name:ja": "アイスクリーム",
      "name:pt": "Gelado",
      "name:pt_BR": "Sorvete",
      "quantity": 1,
      "total": 10.0
    }
  ],
  "localtime": "2013-04-30T14:57:00+01:00",
  "store_reference": "1",
  "total": 10.0,
  "transaction_id": "0011120008"
}

Translation Alternatives¶

Alternative fields are used to provide translations for certain fields. The Item Object’s ‘name field is an example of such a field. These translations can be used to provide a receipt in multiple languages side-by-side, to facilitate providing the receipt in a language appropriate to the user, or user selection of the language the receipt is displayed in.

Translation field’s alternative names are constructed using an RFC 5646 language tag (but using an underscore _ instead of a hyphen - to separate subtags.) For example, to provide an alternative for the field name for French the one would use: name:fr; or for German as used in Austria: name:de_AT. To avoid storing ambiguous language tags, the correct case of the various subtags must be used or the submission will fail with a schema validation error.

Creating or Updating Stores¶

Stores can be created or updated from a receipt, but only after this feature has been enabled. If you have not requested this feature, posting a store along with a receipt will result in a 422 Unprocessable Entity response.

To create or update a store, post both a store reference and a valid store object along with the receipt. The store will be created or updated as appropriate if this feature has been enabled. When posting a receipt without a store, the previously created (or updated) data associated with the posted store reference will be used.

Example request:

POST /receipts HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json
Content-Length: 628
Content-Type: application/json

{
  "identifier": "990000000001",
  "items": [
    {
      "name": "Cufflinks",
      "quantity": 1,
      "total": 10.0,
      "vat": {
        "amount": 0.0,
        "rate": 0.0
      }
    }
  ],
  "localtime": "2013-04-30T14:57:00+01:00",
  "store": {
    "address": [
      "99 Foo St"
    ],
    "city": "London",
    "country": "GBR",
    "locale": "en_GB",
    "name": "Test Store",
    "phone": "+440000000000",
    "postcode": "W124AF",
    "timezone": "Europe/London"
  },
  "store_reference": "1",
  "total": 10.0,
  "transaction_id": "0011120008",
  "vat": [
    {
      "amount": 0.0,
      "rate": 0.0
    }
  ]
}

Example response:

HTTP/1.1 201 Created
Content-Length: 34
Content-Type: application/json; charset=UTF-8
Location: https://api.ereceipts.co.uk/receipts/513e2391ee5e525ff9000000

{"id": "513e2391ee5e525ff9000000"}

Example error response:

HTTP/1.1 422 Unprocessable Entity
Content-Length: 103
Content-Type: application/json

{
  "description": "store can not be set or updated from receipt",
  "status": "unprocessable entity"
}