Get all receipts for a chain or customer
You can use the Spaaza API to get individual receipt objects or all receipts for a customer. This can be used to provide a customer with access to their full purchase history as well as their individual purchases. Spaaza also makes a PDF of the receipt available for the customer.
Get All Receipts for a Chain
Sample JSON output for two receipts is shown below:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"receipts": [{
"id": 32892596,
"retailer_basket_code": "600240649-1497440106",
"timestamp": "2019-06-14T11:35:06Z",
"type": "online",
"quantity": 1,
"currency": {
"currency_id": 2,
"currency_code": "EUR",
"currency_name_en": "Euro",
"currency_symbol": "€"
},
"subtotal": 43.9,
"total_value": 43.9,
"shipping_charge": 3.26,
"payment_methods": null,
"employee": {
"code": null,
"name": null
},
"line_items": [{
"name": "ACME HONEYCOMB GREEN",
"retailer_product_code": "ACME00001",
"quantity": 1.05,
"item_is_promotional": false,
"sale_price": 39.95,
"original_price": 39.95,
"basket_item_subtotal": 39.95,
"is_identified": true,
"excluded_from_spaaza": false,
"barcode": "3385100168132",
"sku": "ACME00001",
"description": "GREEN HONEYCOMB TOP",
"metadata": {
"barcode": "3385100168132",
"color": "",
"size": null
}
}],
"tax_lines": null,
"chain": {
"id": 1743,
"name": "ACME",
"type": "chain",
"email": "acme@spaaza.com",
"currency": "Euro",
"currency_symbol": "€",
"receipts_service_active": false,
"business": null,
"webhook_config_url": null,
"webhook_config_basic_auth_user": null,
"webhook_config_basic_auth_pass": null
},
"shopper": {
"id": 3140280,
"first_name": "Marcella",
"last_name": "Janssen",
"address_streetname": "Groningenstraat",
"address_housenumber": "466",
"address_housenumber_extension": "2",
"address_towncity": "Lisse",
"address_postalcode": "2152 AB",
"country_code": "NL",
"gender": "F",
"birthday": "1977-12-11",
"username": "test2@example.com",
"signup_channel": null,
"address_line_2": null,
"address_line_3": null,
"address_regionstate": null,
"member_number": "100002",
"email": "test2@example.com",
"registered": false,
"send_email_receipt": true,
"member_program": {
"program_name": "spaaza",
"member_number": "100002"
},
"shipping_address": null,
"billing_address": null
},
"notes": null,
"monetary_wallet": null,
"points_wallet": null,
"basket_vouchers": []
},
{
"id": 32901174,
"retailer_basket_code": "600240649-1498034963",
"timestamp": "2019-06-21T08:49:23Z",
"type": "in_store",
"quantity": 2,
"currency": {
"currency_id": 2,
"currency_code": "EUR",
"currency_name_en": "Euro",
"currency_symbol": "€"
},
"subtotal": 43.9,
"total_value": 43.9,
"shipping_charge": 3.26,
"payment_methods": null,
"employee": {
"code": null,
"name": null
},
"line_items": [{
"name": "ACME STICK UP TEE",
"retailer_product_code": "ACME07249",
"quantity": 1,
"item_is_promotional": false,
"sale_price": 39.955,
"original_price": 229.955,
"basket_item_subtotal": 39.95,
"is_identified": true,
"excluded_from_spaaza": false,
"barcode": "3385100168687",
"sku": "ACME07249",
"description": "BLACK TEE SHIRT",
"metadata": {
"barcode": "3385100168687",
"color": "",
"size": null
}
},
{
"name": "ACME AFRICA TEE",
"retailer_product_code": "ACME96302",
"quantity": 1,
"item_is_promotional": false,
"sale_price": 219.95,
"original_price": 219.95,
"basket_item_subtotal": 219.95,
"is_identified": true,
"excluded_from_spaaza": false,
"barcode": "3385100168742",
"sku": "ACME96302",
"description": "MASAI-THEMED TEE SHIRT",
"metadata": {
"barcode": "3385100168742",
"color": "",
"size": null
}
}
],
"tax_lines": null,
"chain": {
"id": 1743,
"name": "ACME",
"type": "chain",
"email": "acme@spaaza.com",
"currency": "Euro",
"currency_symbol": "€",
"receipts_service_active": false,
"business": {
"id": 1578,
"name": "Test branch",
"branch_code": "0192",
"address": {
"address_1": "Maastrichtstraat",
"address_2": null,
"address_3": null,
"towncity": "Alkmaar",
"postalcode": "1701 AB",
"latitude": 52.86347800002301,
"longitude": 4.749566000001578
}
},
"webhook_config_url": null,
"webhook_config_basic_auth_user": null,
"webhook_config_basic_auth_pass": null
},
"shopper": {
"id": 3140280,
"first_name": "Mark",
"last_name": "Jansen",
"address_streetname": "Utrechtsestraat",
"address_housenumber": "23",
"address_housenumber_extension": "2",
"address_towncity": "Lisse",
"address_postalcode": "2148 AB",
"country_code": "NL",
"gender": "F",
"birthday": "1988-02-01",
"username": "test42@example.com",
"signup_channel": null,
"address_line_2": null,
"address_line_3": null,
"address_regionstate": null,
"member_number": "1090043",
"email": "test2@ecomni.nl",
"send_email_receipt": true,
"registered": true,
"member_program": {
"program_name": "spaaza",
"member_number": "1090043"
},
"shipping_address": null,
"billing_address": null
},
"notes": null,
"monetary_wallet": null,
"points_wallet": null,
"basket_vouchers": []
}
]
}
}
Sample CSV file output is shown below:
id,retailer_basket_code,timestamp,type,items_count,currency_code,currency_symbol,subtotal,total_value,shipping_charge,employee_code,employee_name,chain_business_id,chain_business_name,chain_business_owner_code,shopper_id,shopper_member_program,shopper_member_number,shopper_authentication_point_identifier,shopper_email,shopper_firstname,shopper_lastname,shopper_gender,shopper_birthday,shopper_country_code,shopper_address_postalcode,notes
32901174,600240649-1498034963,2019-06-21T08:49:23+00:00,online,1,EUR,€,43.90,43.90,3.26,,,,,,3140280,spaaza,100002,661196,test2@example,Marcella,"van der Jansen",F,1977-01-14T00:00:00+00:00,NL,"2150 AD",
Overview
- Call name: get-receipts
- Endpoint URL: https://api0.spaaza.com/get-receipts or https://api0.spaaza.com/get-receipts.csv
- Request methods: GET
- Response Content-Type: application/json OR application/force-download with CSV file download
- Auth required: yes
The get-receipts API endpoint returns all receipts for a chain, given the chain ID. It is possible to pass parameters to the endpoint so that it shows all receipts within a particular time period, all receipts for a particular branch or receipts matching various other parameters (see below).
When called without a suffix at the end of the URL or with a .json suffix the endpoint will return an array in the JSON response:
receipts, which are receipts matching the request parameters.
When called via the endpoint URL ending in .csv the endpoint will automatically set the response content-type to application/force-download and respond with a downloadable CSV file. Please see the section entitled “CSV Response Fields” below.
Note that the response is streamed, the API server does not buffer receipts and wait until all are processed before sending.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.4.2 | Return float values for line item quantities |
Permissions and Authentication
This API call requires a valid Spaaza session. The session can be as follows:
- Admin authentication: the performing user needs to be logged in and have
read accessto the entity (business or chain) to which the user is connected. - Privileged authentication: the use of privileged authentication is permitted for this endpoint.
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| chain_id (integer) required | The id of the chain for which the information is being requested. |
| user_id (integer) optional | The Spaaza ID of a particular user. Adding this parameter only returns receipts associated with that user ID. |
| max_created_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the latest creation date/time for which receipts are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T14:05:20+00:00”, “2018-09-19T08:05:20-06:00”, “2018-09-19T14:05:20Z” |
| max_created_datetime_relative (string) optional, overrides max_created_datetime | A string representing, relative to the current time, the latest creation date/time for which receipts are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “+6 days”, “3 weeks”, “+6 months -5 days +2 minutes” |
| min_created_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the earliest creation date/time for which receipts are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T13:27:56+00:00”, “2018-09-19T07:27:56-06:00”, “2018-09-19T13:27:56Z” |
| min_created_datetime_relative (string) optional, overrides min_created_datetime | A string representing, relative to the current time, the earliest creation date/time for which receipts are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “7 days”, “-13 weeks”, “-6 months 5 days -2 minutes” |
| branch_business_id (integer) optional | The Spaaza ID of a branch stored in the Spaaza system. If this parameter is passed, only receipts will be returned which were created in the store specified. Usually the branch_business_owner_code parameter is used by retailers instead of this parameter. If both this parameter and the branch_business_owner_code parameter are passed, an error is generated. |
| branch_business_owner_code (string) optional | The retailer’s identifier for a branch, usually known as a branch code. If this parameter is passed, only receipts will be returned which were created in the store specified. If both this parameter and the branch_business_id parameter are passed, an error is generated. |
| retailer_basket_code (string) optional | A retailer transaction code or receipt number. If this parameter is passed, only receipts will be returned which match this exact transaction code or receipt number. For retailers with strict transaction code restrictions enabled, only a single receipt will be returned. |
| number_results (integer) optional | The (maximum) number of results required in the response. The default action for CSV output is to return all possible receipts. For JSON output the maximum number of results returned for a single request is 500. |
| results_offset (integer) optional | The result number at which to start. For example, if there are 1000 receipts, giving a results_offset of 500 will start at receipt 500. Numbering starts at 0. |
Output
The output contains information about vouchers and the users they are associated with.
CSV Response Fields
When called via the endpoint URL ending in .csv the endpoint returns a downloadable CSV file named vouchers.csv. The CSV file contains a header row in the first line followed by a single line per voucher.
The fields shown below are represented in the CSV file in the order shown. Unpopulated fields follow CSV convention and are left blank. Fields containing special characters are surrounded by double quotes - e.g. "String with spaces" - following CSV convention. Other fields may be added to the CSV file in future, and these will be added at the end of each line.
| Field | Description |
|---|---|
| id (integer) | The unique ID of the receipt in the Spaaza system. |
| retailer_basket_code (string) | The retailer transaction code or receipt number. |
| timestamp (ISO-8601 timestamp) | The date and time the receipt was created. |
| type (string) | The type of receipt. Current ossible values are “online” or “in_store”. |
| items_count (integer) | The count of the number of items purchased in the receipt. |
| currency_code (string, ISO-4217 currency code) | The ISO-4217 three-letter currency code of the voucher currency, e.g. “EUR” or “ZAR”. |
| currency_symbol (string, ISO-4217 currency symbol) | The ISO-4217 three-letter currency symbol of the voucher currency, e.g. “€” or “$”. |
| subtotal (float) | The subtotal of the receipt. |
| total_value (float) | The total transaction value of the receipt. |
| shipping_charge (float) | The shipping charge amount of the receipt. This is stored separately from the total value. |
| employee_code (string) | The employee code of the employee handling the transaction. |
| employee_name (string) | The name of the employee handling the transaction. |
| chain_business_id (integer) | The unique ID in the Spaaza system of the branch in which the transaction was made. |
| chain_business_name (string) | The name of the branch in which the transaction was made. |
| chain_business_owner_code (string) | The retailer’s identifier for the branch in which the transaction was made, usually known as a branch code. |
| shopper_id (integer) | The unique ID of the shopper/customer in the Spaaza system. |
| shopper_member_program (string) | The name of the member program of which the shopper/customer is a member. Usually this is ‘spaaza’. |
| shopper_member_number (string) | The member number of the shopper/customer in the program. |
| shopper_authentication_point_identifier (string) | The ID of the user in a third party webshop or other identity system. |
| shopper_email (string) | The email address of the shopper/customer, also known as the ‘username’. |
| shopper_firstname (string) | The first name of the shopper/customer. |
| shopper_lastname (string) | The last name of the shopper/customer. |
| shopper_gender (string) | The gender of the shopper/customer. If populated, two values are possible, “M” and “F”. |
| shopper_birthday (ISO-8601 timestamp) | The birth date of the shopper/customer. |
| shopper_country_code (string) | The ISO ALPHA-2 code for the country of the shopper/customer. |
| shopper_address_postalcode (string) | The shopper/customer’s postal or zipcode. |
| notes (string) | Any notes associated with the receipt. |