Versioning
Introduction
Occasionally Spaaza makes changes to the payload sent to or response received from an API endpoint. This may include adding new request or response fields. In order to maintain backwards compatibility with existing API clients a versioning policy is put in place. The aim of this policy is to make using endpoint features as simple as possible.
Usually a Spaaza API endpoint maintains backward compatibility without requiring special flags, but in the case that a specific version is required, the API documentation for that endpoint will show clearly what is needed. If there is no information about versioning in the documentation for a specific endpoint, then there is no need to do anything. Spaaza recommends sending an appropriate version header with all API requests.
Occasionally version-specific changes become available in the Spaaza API which affect multiple, or all, endpoints. This kind of change is described in the section API-wide version information
below. Again, this kind of change is designed to be non-breaking and as backwards-compatible as possible.
It should be noted that Spaaza’s approach is generally that we may add optional request fields, or fields to response JSON, without a version change, but that we will only remove fields, or change their type or name, in a new API version, and that that change should avoid affecting API clients consuming endpoints with existing versions.
Using a specific endpoint version
With most Spaaza API endpoints version-specific differences are implemented. In order to use the latest version of an API endpoint, a version header is sent along with the request to the API endpoint. The documentation for a specific endpoint will always contain information about which version number should be used if there are changes differences that are specific to that endpoint.
There are also version-specific differences that apply to all endpoints, such as how errors are formatted in API responses. These are detailed in the ‘API-wide version information’ section below.
The following header is used for specifying a version:
X-Spaaza-API-Version: <version number>
Spaaza uses standard semantic numeric major.minor.fix version numbering, for example:
X-Spaaza-API-Version: 1.4.10
NOTE that if no X-Spaaza-API-Version
header is supplied then a version number of 1.0.0
is assumed.
API-wide version information
This section includes information about version-specific changes which affect multiple, or all, endpoints in the Spaaza API. In the case that these changes affect all endpoints, for example a change in the way error responses are handled between different versions, a description of the change is not usually included in the documentation for any specific individual endpoints.
A description of each of this kind of version-specific change is shown below.
1.5.1 - Multiple updates
- New - Google and Apple wallet integration for showing membership passes
- New - allow an end user to request to update their own password
- New - “Favorite Store” - added functionality calculating and returning a user’s favorite store in API endpoints, based on their recent purchase history
- New - “ARTS POSlog” - added functionality to import ARTS (Association for Retail Technology Standards) POSlog transaction files into the Spaaza system
- New - added cost price functionality to basket items in
get-basket-price
andadd-basket
calls in order to allow profit margin calculations and analytics sliced by various parameters such as store, product, user segment etc - Improved - remove campaign information from the
get-user-vouchers
response - Improved - added a
campaign_types
filter to theget-campaigns
endpoint - Improved - added
programme_opted_in
to business - Improved - added
created_date
andlast_modified_date
to user in responses to certain calls - Improved - standardised custom headers to use
X-Spaaza-
prefix - Improved - upgraded unit price rounding to max 4 decimal places in basket items and receipt line items
- Improved - split barcode assignments by type in campaign responses
- Improved - add campaign promotion type to basket voucher in responses
- Improved - show improved task log output in Console
- Improved - various indexing improvements to improve performance of vouchers and basket calls
- Improved - dummy email domain now not included as email field in profile completion campaign
- Improved - nullify
business_owner_code
when blank string is passed as parameter - Improved - add support for Shopify authentication to
get-campaigns
endpoint - Fixed - bug when you alter a campaign via API that would set campaign fields null unintentionally.
- Fixed - bug when checking Campaign assignments on a Basket Campaign
- Fixed - stop
get-basket-price
,add-basket
andclaim-basket
working with obfuscated users - Fixed - issue with calculating an adjusted basket for an existing basket which did not have a user
- Fixed - issue setting null
user_segment_id
andexcluded_user_segment_id
in campaigns calls - Fixed - issue with campaign returning an error if last review date was null
1.5.0 - Multiple updates
- New - “Business Groups” - features to group chain branches and introduce the concept of a user belonging to a business group, which can be used as a region and based on user location, and used to target campaigns.
- New - “Meal Deal Promotions” - promotional campaigns allowing grouping of campaign assignments, and redemption in basket calls
- New - “Client-Led promotions” - allow basket API endpoint clients (e.g. a POS or e-commerce) to define which promotions are applied to items in a basket, rather than requiring a call to
get-basket-price
to do that - New - “Fixed Monetary Discount” - promotional campaigns allowing a fixed monetary discount to be applied to each matching item in a basket
- Improved - improve performance of basket call segment checking
- Improved - improve performance of database exception handling
- Improved - Garden Connect integration customer handling
- Improved - logic applied in voucher expiry notification task
- Improved - improvements to loyalty review task
- Improved - add
current_count
field to item purchase count campaign inget-campaigns
response - Fixed - wallet amount was being awarded for all contributing campaigns in certain exchange/return transaction scenarios
- Fixed - issue where item purchase count progress was being issued when purchasing reward items
- Fixed - issue with artificial user in get-basket-price call
- Fixed - issue where double HTTP response code was being sent in certain exception responses
- Fixed - issue where unredeemable percentage discount vouchers were being returned in
get-basket-price
response even ifvouchers_lock_exclusively
was not set to true - Fixed - issue where
add-basket
would return an error if a basket voucher was submitted for redemption twice in a single call - Fixed - issue where vouchers for non-promotional campaigns were not being returned in the response to
get-basket-price
if the associated campaigns had campaign assignments - Fixed - issue where
get-user-vouchers
was returning incorrectvoucher_amount
values for vouchers which had been claimed and processed byget-basket-price
, but not yet redeemed - Fixed - issue displaying content campaigns in
get-campaigns
- Deprecation notice - All non-voucher fields (
promotions
andwallet
) to be removed from version 1.5.1 ofget-user-vouchers
1.4.11 - Update to get-campaigns
- Switch default behaviour of
exclude_inactive
in theget-campaigns
API endpoint. Previously, inactive campaigns would be included in the API response by default unless theexclude_inactive
parameter was set totrue
. Now, inactive campaigns are excluded by default unlessexclude_inactive
is set tofalse
.
1.4.10 - Updates to add-user
, get-user
, get-login-status
,alter-user
, login
and get-card
- Update gender field in
user
object to support male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.
1.4.9 - Updates to shopper.transaction
webhook
- Update
shopper.transaction
webhook replaceshopper
object withuser
object.
1.4.8 - Additions to responses to get-basket-price
and add-basket
- New structure for
purchase_progress
array in response toget-basket-price
andadd-basket
- Additions of
vouchers_created
array in response toget-basket-price
andadd-basket
1.4.7 - Updates to add-basket
- Update the
item_price
request field to change definition item price net of vouchers and other Spaaza rewards to be redeemed. - Add the
item_original_price
request field to send the original gross per-unit price of a basket item before Spaaza vouchers and rewards.
1.4.6 - Updates to add-user
, get-user
, get-login-status
,alter-user
, login
and get-card
- Update
birthday
date format inuser_info
response object toYYYY-MM-DD
.
1.4.5 - Updates to add-basket
and get-card
- Update
add-basket
response to includeitem_original_price
in request object for basket item and to displayvoucher_distribution_estimated
warning for requests that include on the fly basket campaign vouchers, but the item_original_price is missing from all the basket items. - Update
get-card
response to returnresult_type
ofget-user-entity-card
when API client version < 1.4.5
1.4.4 - Update get-card
display for cashback
campaigns.
- Returns Campaigns of
type
cashback
ascashback
within thepromotions
block.
1.4.3 - Update currency
display in get-card
response
- Returns a standard
currency
object across allcampaign
types withinget-card
promotions block.
1.4.2 - Allow float values for basket item quantities
- Allow float values for basket (line) item quantities in
get-basket-price
andadd-basket
- Update parameters to allow multiple parallel wallets
- Previous name of
basket_vouchers
array in response JSON ofget-vouchers
changed tovouchers
.
1.4.1 - Remove URL format requirements
- Remove requirement for .json or .php suffixes at the end of API endpoint URLs
- Remove requirement for
v1/
in API endpoint URLs
1.4.0 - Updates to formatting of JSON error responses
- Error responses for all API endpoints updated to reflect semantic correction of
errors
->error
where only a single error is returned.
API clients using a version number less than 1.4.0 will receive the previous error formatting in the JSON returned in the error response. Documentation for older clients is available on request.
1.1.8 - Updates to formatting of JSON in get-basket-price
and add-basket
endpoints.
get-basket-price
endpoint request and response JSON updated to change parameter namesadd-basket
endpoint request and response JSON updated to change parameter nameslock-voucher
endpoint parameters and response JSON updated to change parameter names
API clients using the above endpoints should use a version number greater than or equal to 1.1.8
. Documentation for older clients is available on request.