Link Search Menu Expand Document

Receipts

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.

Receipt Object

Example response


{
  "id": 123456,
  "timestamp": "2017-07-03T11:56:04Z",
  "type": "in_store",
  "download_url": "https://s3-eu-west-1.amazonaws.com/test01-receipts-bucket/receipts/123456.pdf",
  "quantity": 1,
  "subtotal": 1000,
  "total_value": 1000,
  "payment_method": "unknown",
  "line_items": [
    {
      "product_id": 0,
      "barcode": "2000046371025",
      "sku": "2000046371025",
      "name": "ACME shorts",
      "description": "the best pair you can buy",
      "type": "shorts",
      "original_price": 1000,
      "quantity": 1.05,
      "sale_price": 1000,
      "vouchers": 0,
      "metadata": {
        "color": "blue",
        "size": "L",
        "image": ""
      },
      "sale_discount": ""
    }
  ],
  "tax_lines": [
      {
        "tax_value": 30.25,
        "order_value": 100.99,
        "rate": 0.21
      },
      {
        "tax_value": 20.55,
        "order_value": 99.99,
        "rate": 0.06
      },
      {
        "tax_value": 19.99,
        "order_value": 200,
        "rate": 1.5
      }
],
  "chain": {
    "id": 1740,
    "name": "ACME",
    "email": "support@acme.co.za",
    "logo_url": "https://s3-eu-west-1.amazonaws.com/receipts-chain-logo/1000.png",
    "website_url": "",
    "currency": "South African Rand",
    "currency_symbol": "R",
    "business": {
      "id": 0,
      "name": "ACME Cape Town",
      "address": {
        "address_1": "1 Table Mountain Drive",
        "address_2": "",
        "address_3": "",
        "towncity": "Cape Town",
        "postal_code": "",
        "country_code": "ZA",
        "location": {
          "lat": -33.962822,
          "lon": 18.4098410
        }
      },
      "phone_number": "+272189777777",
      "email": "table-mountain@acme.co.za",
      "website_url": ""
    },
    "receipts_service_active": true
  },
  "shopper": {
    "id": 897654,
    "user_name": "",
    "entity_code": "",
    "first_name": "John",
    "last_name": "Smith",
    "country_code": "",
    "gender": "M",
    "birthday": "1982-05-30",
    "total_points_balance": 0,
    "email": "john.smith@email.com",
    "registered": true,
    "shipping_address": {
      "address_1": "",
      "address_2": "",
      "address_3": "",
      "towncity": "",
      "postal_code": "",
      "country_code": "",
      "location": {
        "lat": 0,
        "lon": 0
      }
    },
    "billing_address": {
      "address_1": "",
      "address_2": "",
      "address_3": "",
      "towncity": "",
      "postal_code": "",
      "country_code": "",
      "location": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "monetary_wallet": {
    "contributions": [
      {
        "amount": 100,
        "campaign_title": "Earn big on every purchase"
      }
    ],
    "total": 1640,
    "title": "ACME Bucks"
  },
  "points_wallet": {
    "contributions": [],
    "total": 0,
    "title": ""
  },
  "basket_vouchers": [
    {
      "campaign_title": "Boardriders Bucks",
      "voucher_text": "",
      "amount": 500,
      "type": "wallet"
    }
  ],
  "loyalty_status": {
      "campaign_id": 2095,
      "name": "Level 1",
      "description": "Level 1 in the Programme",
      "loyalty_level_id": 2,
      "points_to_proceed_next_level": 500,
      "points_to_remain_current_level": 220,
      "maintenance_points_level": 200,
      "last_review_date": "2019-04-04T00:05:22+00:00",
      "next_review_date": "2020-04-04T00:05:22+00:00",
      "date_reached": "2019-06-06T08:06:14+00:00"
  }
}


Fields in the Receipt object

The following fields are returned in the receipt object.

Identifying the receipt

Details of the receipt

Field Description
id id of the receipt, this should be the same ID as used by the system that completed the sale (webshop, POS etc)
timestamp time of the receipt creation
download_url a URL to access a PDF for the receipt
quantity the number of items in the receipt
subtotal subtotal amount of the receipt without VAT
total_value the amount of the receipt with VAT
payment_method how the customer paid for the transaction

Line items

An array of all the products purchased in the transaction.

Field Description
product_id Spaaza’s product ID
barcode the barcode of the product
sku the SKU of the product
name the name of the product
description the description of the product
type the type or category of the product
original_price the original price of the product
quantity the quantity of each item in the transaction
quantity_unit the unit used for the quantity of each item in the transaction
sale_price what the final selling price was for the item
vouchers the total value of any vouchers redeemed against the item
color (metadata) the color of the product
size (metadata) the size of the product
image (metadata) a URL for an image of the product
sale_discount the discount applied on the sale of the product

Tax lines

An array of the taxes applied to the transaction.

Field Description
tax_value the total amount of the applicable tax on the order
order_value the monetary value of the order that the tax applies to
rate the applicable rate or percentage of the tax

Chain

Details of the retailer (referred to as a chain by Spaaza).

Field Description
id Spaaza’s ID for the retailer (or chain)
name the name of the retailer
email the contact details of the retailer
logo_url a URL for the logo of the retailer
currency the currency name of the retailer
currency_symbol the currency symbol of the retailer
receipts_service_active whether the chain has activate the receipts service in Spaaza

Business

Within the “chain” the details of the physical store where the transaction occured (referred to as a business by Spaaza) are included.

Field Description
id Spaaza’s store ID
name the name of the store
address a section that includes the address details of the store
phone_number the store’s phone number
email the store’s email address
website_url the store’s website URL

Shopper

The shopper (also referred to as a user or customer in other parts of this documentation) who completed the transaction.

Field Description
id Spaaza’s ID for the shopper. Note that this is not the same number as is shown on the customer’s loyalty card or in an app (see entity code)
user_name a user name for the shopper
entity_code Spaaza’s entity code which is the customer’s loyalty card number.
first_name tte customer’s first name
last_name the customer’s last name
country_code the ISO ALPHA-2 code for the customer’s country
gender the customer’s gender
birthday the customer’s birthday
total_points_balance the customer’s total points balance
email the customer’s email address
registered whether the customer is ‘registered’ - the definition of ‘registered’ is determined by the retailer
shipping_address a section which includes the shipping address details of the customer
billing_address a section which includes the shipping address details of the customer

Monetary Wallet

If the retailer (or Chain) is using Spaaza’s Wallet functionality then the details of what was earned on the shopper’s wallet as a result of the transaction are included in the receipt.

Field Description
total the total amount in the customer’s wallet directly after the transaction
title the title of the wallet rewards

Monetary Wallet Contributions

The contributions section in the Monetary Wallet is an array of campaigns that added value to the customer’s wallet as a result of the transaction. For example: “customers earn 5% back” and “customer get an extra 5% back this weekend”.

Field Description
amount the amount added by the contributor campaign
campaign_title the title of the contributor campaign

Points Wallet

If the retailer (or Chain) is using Spaaza’s points functionality then the details of the points earned as a result of the transaction are included in the receipt.

Field Description
total the total amount of points directly after the transaction
title the title of the points program

Points Wallet Contributions

The contributions section in the Points Wallet is an array of campaigns that added points as a result of the transaction. For example: “customers earn 100 points on every €100 spent” and “customer get an extra 100 points on every €100 spent this weekend”.

Field Description
amount the amount added by the contributor campaign
campaign_title the title of the contributor campaign

Template content

Some styling and content settings for a receipt.

Field Description
subject a custom subject for a receipt email
background_color a custom color, typucally used for any receipt actions (ie a download PDF button)

Get All Receipts For a User

curl "https://services-[API_ENVIRONMENT].spaaza.com/receipts/?shopper_id=1234567"

The above command returns JSON structured like this:

[
  {
    "id": 123456,
    "timestamp": "2017-07-03T11:56:04Z",
    "type": "in_store",
    "download_url": "https://s3-eu-west-1.amazonaws.com/test01-receipts-bucket/receipts/123456.pdf",
    "quantity": 1,
    "subtotal": 1000,
    "total_value": 1000,
    "payment_method": "unknown",
    "line_items": [
      {
        "product_id": 0,
        "barcode": "2000046371025",
        "sku": "2000046371025",
        "name": "ACME shorts",
        "description": "the best pair you can buy",
        "type": "shorts",
        "original_price": 1000,
        "quantity": 1.055,
        "quantity_unit": "kg",
        "sale_price": 1000,
        "vouchers": 0,
        "metadata": {
          "color": "blue",
          "size": "L",
          "image": ""
        },
        "sale_discount": ""
      }
    ],
    "tax_lines": [],
    "chain": {
      "id": 1740,
      "name": "ACME",
      "email": "support@acme.co.za",
      "logo_url": "https://s3-eu-west-1.amazonaws.com/receipts-chain-logo/1000.png",
      "website_url": "",
      "currency": "South African Rand",
      "currency_symbol": "R",
      "business": {
        "id": 0,
        "name": "ACME Cape Town",
        "address": {
          "address_1": "1 Table Mountain Drive",
          "address_2": "",
          "address_3": "",
          "towncity": "Cape Town",
          "postal_code": "",
          "country_code": "ZA",
          "location": {
            "lat": -33.962822,
            "lon": 18.4098410
          }
        },
        "phone_number": "+272189777777",
        "email": "table-mountain@acme.co.za",
        "website_url": ""
      },
      "receipts_service_active": true
    },
    "shopper": {
      "id": 897654,
      "user_name": "",
      "entity_code": "",
      "first_name": "John",
      "last_name": "Smith",
      "country_code": "",
      "gender": "M",
      "birthday": "1982-05-30",
      "total_points_balance": 0,
      "email": "john.smith@email.com",
      "registered": false,
      "shipping_address": {
        "address_1": "",
        "address_2": "",
        "address_3": "",
        "towncity": "",
        "postal_code": "",
        "country_code": "",
        "location": {
          "lat": 0,
          "lon": 0
        }
      },
      "billing_address": {
        "address_1": "",
        "address_2": "",
        "address_3": "",
        "towncity": "",
        "postal_code": "",
        "country_code": "",
        "location": {
          "lat": 0,
          "lon": 0
        }
      }
    },
    "monetary_wallet": {
      "contributions": [
        {
          "amount": 100,
          "campaign_title": "Earn big on every purchase"
        }
      ],
      "total": 1640,
      "title": "ACME Bucks"
    },
    "points_wallet": {
      "contributions": [],
      "total": 0,
      "title": ""
    },
    "basket_vouchers": [
      {
        "campaign_title": "Boardriders Bucks",
        "voucher_text": "",
        "amount": 500,
        "type": "wallet"
      }
    ]
  },
  {
    "id": 678910,
    "timestamp": "2017-07-03T11:35:52Z",
    "type": "in_store",
    "download_url": "https://s3-eu-west-1.amazonaws.com/test01-receipts-bucket/receipts/77888.pdf",
    "quantity": 1,
    "subtotal": 2000,
    "total_value": 2000,
    "payment_method": "unknown",
    "line_items": [
      {
        "product_id": 0,
        "barcode": "2000046371025",
        "sku": "2000046371025",
        "name": "Best tee",
        "description": "The best t-shirt money can buy",
        "type": "T-shirt",
        "original_price": 2000,
        "quantity": 1,
        "sale_price": 2000,
        "vouchers": 0,
        "metadata": {
          "color": "grey",
          "size": "S",
          "image": ""
        },
        "sale_discount": ""
      }
    ],
    "tax_lines": [],
    "chain": {
      "id": 1740,
      "name": "ACME",
      "email": "support@acme.co.za",
      "logo_url": "https://s3-eu-west-1.amazonaws.com/receipts-chain-logo/1740.png",
      "website_url": "",
      "currency": "South African Rand",
      "currency_symbol": "R",
      "business": {
        "id": 1,
        "name": "ACME Waterfront",
        "address": {
          "address_1": "2 Waterfront bay",
          "address_2": "",
          "address_3": "",
          "towncity": "Cape Town",
          "postal_code": "",
          "country_code": "ZA",
          "location": {
            "lat": -33.901988,
            "lon": 18.420828
          }
        },
        "phone_number": "+27218998765",
        "email": "waterfront@acme.co.za",
        "website_url": ""
      },
      "receipts_service_active": true
    },
    "shopper": {
      "id": 897654,
      "user_name": "",
      "entity_code": "",
      "first_name": "John",
      "last_name": "Smith",
      "country_code": "",
      "gender": "M",
      "birthday": "1982-05-30",
      "total_points_balance": 0,
      "email": "john.smith@email.com",
      "registered": false,
      "shipping_address": {
        "address_1": "",
        "address_2": "",
        "address_3": "",
        "towncity": "",
        "postal_code": "",
        "country_code": "",
        "location": {
          "lat": 0,
          "lon": 0
        }
      },
      "billing_address": {
        "address_1": "",
        "address_2": "",
        "address_3": "",
        "towncity": "",
        "postal_code": "",
        "country_code": "",
        "location": {
          "lat": 0,
          "lon": 0
        }
      }
    },
    "monetary_wallet": {
      "contributions": [
        {
          "amount": 200,
          "campaign_title": "Earn big on every purchase"
        }
      ],
      "total": 1540,
      "title": "ACME Bucks"
    },
    "points_wallet": {
      "contributions": [],
      "total": 0,
      "title": ""
    },
    "basket_vouchers": [],
    "template_content": {
      "subject": "",
      "background_color": ""
    }
  }
]

This endpoint returns all receipts objects for a specific user.

HTTP Request

Use the following GET request to request all receipts for a shopper:

GET https://services-[API_ENVIRONMENT].spaaza.com/receipts?shopper_id=<ID>

The API_ENVIRONMENT value varies according to whether the request is being made to Spaaza’s production or staging API:

Environment API_ENVIRONMENT value
Production prod
Staging test01

Headers

For admin or user authentication the following headers are required:

Header Description
Session-User-Id ID of the user obtained from the login endpoint
Session-Key key of the session obtained from the login endpoint
Session-Chain-Id the ID of the Spaaza chain or retailer

For privileged authentication the following headers are required:

Header Description
Session-Chain-Id the ID of the Spaaza chain or retailer
Authorization Bearer access token see: privileged

The following authentication methods are permitted:

Method Description
user A session generated by an end-user login.
or  
admin A session generated by administrative user login.
or  
privileged A token generated to privileged users.

Query Parameters

This API accepts the following parameters:

Parameter Description
shopper_id required The Spaaza User ID of the shopper/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.95,
						"original_price": 229.95,
						"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 access to 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.

Get a Specific Receipt

curl "https://services-[API_ENVIRONMENT].spaaza.com/receipts/12345678"

The above command returns JSON structured like this:

{
  "id": 123456,
  "timestamp": "2017-07-03T11:56:04Z",
  "type": "in_store",
  "download_url": "https://s3-eu-west-1.amazonaws.com/test01-receipts-bucket/receipts/123456.pdf",
  "quantity": 1,
  "subtotal": 1000,
  "total_value": 1000,
  "payment_method": "unknown",
  "line_items": [
    {
      "product_id": 0,
      "barcode": "2000046371025",
      "sku": "2000046371025",
      "name": "ACME shorts",
      "description": "the best pair you can buy",
      "type": "shorts",
      "original_price": 1000,
      "quantity": 1,
      "sale_price": 1000,
      "vouchers": 0,
      "metadata": {
        "color": "blue",
        "size": "L",
        "image": ""
      },
      "sale_discount": ""
    }
  ],
  "tax_lines": [],
  "chain": {
    "id": 1740,
    "name": "ACME",
    "email": "support@acme.co.za",
    "logo_url": "https://s3-eu-west-1.amazonaws.com/receipts-chain-logo/1000.png",
    "website_url": "",
    "currency": "South African Rand",
    "currency_symbol": "R",
    "business": {
      "id": 0,
      "name": "ACME Cape Town",
      "address": {
        "address_1": "1 Table Mountain Drive",
        "address_2": "",
        "address_3": "",
        "towncity": "Cape Town",
        "postal_code": "",
        "country_code": "ZA",
        "location": {
          "lat": -33.962822,
          "lon": 18.4098410
        }
      },
      "phone_number": "+272189777777",
      "email": "table-mountain@acme.co.za",
      "website_url": ""
    },
    "receipts_service_active": true
  },
  "shopper": {
    "id": 897654,
    "user_name": "",
    "entity_code": "",
    "first_name": "John",
    "last_name": "Smith",
    "country_code": "",
    "gender": "M",
    "birthday": "1982-05-30",
    "total_points_balance": 0,
    "email": "john.smith@email.com",
    "registered": false,
    "shipping_address": {
      "address_1": "",
      "address_2": "",
      "address_3": "",
      "towncity": "",
      "postal_code": "",
      "country_code": "",
      "location": {
        "lat": 0,
        "lon": 0
      }
    },
    "billing_address": {
      "address_1": "",
      "address_2": "",
      "address_3": "",
      "towncity": "",
      "postal_code": "",
      "country_code": "",
      "location": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "monetary_wallet": {
    "contributions": [
      {
        "amount": 100,
        "campaign_title": "Earn big on every purchase"
      }
    ],
    "total": 1640,
    "title": "ACME Bucks"
  },
  "points_wallet": {
    "contributions": [],
    "total": 0,
    "title": ""
  },
  "basket_vouchers": [
    {
      "campaign_title": "Boardriders Bucks",
      "voucher_text": "",
      "amount": 500,
      "type": "wallet"
    }
  ],
          "loyalty_status": {
              "campaign_id": 2095,
              "name": "Level 1",
              "description": "Level 1 in the Programme",
              "loyalty_level_id": 2,
              "points_to_proceed_next_level": 500,
              "points_to_remain_current_level": 220,
              "maintenance_points_level": 200,
              "last_review_date": "2019-04-04T00:05:22+00:00",
              "next_review_date": "2020-04-04T00:05:22+00:00",
              "date_reached": "2019-06-06T08:06:14+00:00"
          }
}

Give a specific id, this endpoint returns the corresponding receipt object.

HTTP Request

Use the following GET request to get an individual receipt:

GET https://services-[API_ENVIRONMENT].spaaza.com/receipts/<id>

The API_ENVIRONMENT value varies according to whether the request is being made to Spaaza’s production or staging API:

Environment API_ENVIRONMENT value
Production prod
Staging test01

Headers

For admin or user authentication the following headers are required:

Header Description
Session-User-Id ID of the user obtained from the login endpoint
Session-Key key of the session obtained from the login endpoint
Session-Chain-Id the ID of the Spaaza chain or retailer

For privileged authentication the following headers are required:

Header Description
Session-Chain-Id the ID of the Spaaza chain or retailer
Authorization Bearer access token see: privileged

The following authentication methods are permitted:

Method Description
user A session generated by an end-user login.
or  
admin A session generated by administrative user login.
or  
privileged A token generated to privileged users.

URL Parameters

This API accepts the following parameters:

Parameter Description
id required Id of the receipt