Link Search Menu Expand Document

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.8 - Multiple updates

  • Added - Added pagination to get-campaign-groups endpoint
  • Added - Added campaign group filter to get-campaigns endpoint to allow filtering campaigns by their campaign group
  • Added - Added the ability to use multiple filters at the same time in get-campaigns endpoint
  • Added - Added a customisable voucher locking period in get-basket-price request

1.5.7 - Multiple updates

  • Added - Maximum values:
    • maximum_basket_total_value_earn: Maximum basket value allowed for campaigns to issue rewards during basket processing
    • maximum_basket_total_value_spend: Maximum basket value allowed for redeeming standalone vouchers in baskets
  • Added - added opt_in_secondary_last_modified_date, which is a datetime field that records the last time opt_in_secondary date changed in User object.
  • Deprecated - the user-specific note field has been replaced by the new Note object, which allows for more flexible and structured note management. The note field will be removed from the response to get-user, get-users and get-card endpoints in version 1.6.0.

1.5.6 - Multiple updates

  • Improved - If a chain does not allow repeated use of retailer_basket_code values for baskets, an exclusive retailer_basket_code parameter in claim-vouchers and lock_voucher will now generate a basket_already_exists error when an associated basket already exists.
  • Improved - Update identity handler after user opt_in_secondary is set in Stripe webhook handler
  • Improved - the get-campaigns endpoint now supports pagination for API requests.

1.5.5 - Multiple updates

  • Improved - In a return transaction, if it is not possible to match a returned item to an original purchase item, the item will be treated as a negatively-priced purchase item in the returning basket and the excluded_from_spaaza parameter will be set to true to avoid applying any Spaaza campaign logic to the item. See returns documentation for more information.
  • Improved - return a warning in basket endpoints when a returned item cannot be matched to an original purchase transaction
  • Improved - return a warning in basket endpoints when sum of item_price amounts for items does not match basket_total_price value

1.5.4 - Multiple updates

  • Added - Split minimum_basket_total_value into two fields:
    • minimum_basket_total_value_earn: Minimum basket value required for campaigns to issue rewards during basket processing
    • minimum_basket_total_value_spend: Minimum basket value required for redeeming standalone vouchers in baskets
  • Added - add-product and add-product-variant endpoints and products now indexed in analytics database
  • Added - added Campaign Groups to group campaigns together, and API endpoints to manage them
  • Added - added Fixed Unit basket voucher and fixed_unit_basket_voucher reward method to campaign award which provides a fixed monetary discount per purchase unit of a matching item
  • Added - added quantity_unit promotion type to basket campaigns - single unit monetary discount
  • Added - added business_format and business_region as campaign assignments
  • Added - added campaign minimum_matching_item_value to basket and other campaigns
  • Added - added content zones functionality and alter-content-page and get-content-page API endpoints to API
  • Added - added end-user signature storage
  • Added - added get-product-variants endpoint with pagination and the ability to filter by barcodes
  • Improved - when all purchase items in a basket have both item_price and item_original_price fields populated, the difference between the two values is used to calculate the redemption amount and distribution of vouchers being redeemed instead of making any reference to previously calculated voucher redemption values. This allows client-specific discounts to still be applied between calls to the get-basket-price and add-basket endpoints, although we recommend caution. See the subsection called Basket Discounts and Vouchers for more information about voucher redemption. (versions >= 1.5.4)
  • Improved - add retailer_basket_code to referral relation and use in redemption tracking
  • Improved - added Item Purchase Count and Progress campaigns to output of user-wallet-ledger
  • Improved - added meal_deal_monetary_discount and cheapest_product_discount promotion types to basket campaigns
  • Improved - added totalvalue transaction message parameter
  • Improved - added address fields to Profile Completion campaign
  • Improved - added business filtering to get-content-page endpoint
  • Improved - added campaign active from/until date to voucher analytics
  • Improved - added campaign type and tag filtering to content pages
  • Improved - added external funding ratio to promotional campaigns allowing 3rd party brands to sponsor them
  • Improved - added extra user information to the response of get-basket-price and add-basket in version >= 1.5.4
  • Improved - added max_reward_quantity recurrence limit to basket campaigns
  • Improved - added privileged authentication to get-businesses API endpoint
  • Improved - added reward redemption count and progress to get-campaigns output for end users
  • Improved - added warning for unrecognised branch by branch_business_owner_code in basket calls
  • Improved - adjusted win spread for competition campaigns relative to budget to avoid win clustering
  • Improved - aligned business term search with expected in get-businesses
  • Improved - allow PurchaseCount campaign to define the number of times a customer can be rewarded
  • Improved - allow chain_id and remove entity_type requirement in basket calls in version >= 1.5.4
  • Improved - allow admin and end-user access to get-businesses endpoint
  • Improved - allow editable campaign assignment groups
  • Improved - allow supplier contribution in a basket campaign to be set to null
  • Improved - allowed multiple campaign assignment groups to be used in meal deal and other promotional basket campaigns
  • Improved - campaign assignments added to responses for content zones
  • Improved - campaign assignments exclude option now only applies to barcode assignments
  • Improved - changed default Purchase Count logic to not include baskets purchased before campaign live date
  • Improved - check whether assigned_groups parameter for campaign is an array
  • Improved - database improvements in communications with Magento 2 REST API and module
  • Improved - enable rewards creation via add-user-purchase-progress for Item Purchase Count campaign and other non-wallets
  • Improved - excluded delete campaigns from campaign groups in responses
  • Improved - extended add-user-purchase-progress endpoint to allow adding Progress and Item Purchase Count campaign amounts
  • Improved - extended free basket competition campaign logic
  • Improved - extended product endpoints to allow product, product variant and barcode deletion
  • Improved - improve min_earn_quantity logic for Matching Item campaign
  • Improved - improvements to competition win rate if budget is behind or ahead
  • Improved - improvements to image upload performance via the API
  • Improved - improvements to user signature upload flow
  • Improved - make budget_period_quantity nullable in competition campaign
  • Improved - make chain_id optional in get-businesses as it’s only needed for admin authentication
  • Improved - remove campaign_budget_constraint_monetary from competition campaign
  • Improved - restrict competition budget period to single day or entire competition validity period for clarity
  • Improved - use campaign voucher text field for voucher text when creating competition vouchers
  • Fixed - allow basket campaigns to give 100% discount instead of 99.99%
  • Fixed - fixed bug in competition campaign award calculation and returns
  • Fixed - fixed issue calculating previous balance in some circumstances in add-user-purchase-progress
  • Fixed - fixed issue creating duplicate rewards in Profile Completion campaign
  • Fixed - fixed issue resolving empty basket vouchers array in basket calls
  • Fixed - fixed issue where it was possible for one competition budget period parameter to be null
  • Fixed - fixed issue where wrong returned basket item field was indexed leading to erroneous analytics data for returns
  • Fixed - fixed issue with BasketCampaign fixed_monetary_discount and add-basket when item_original_price is missing
  • Fixed - fixed issue with max_reward_quantity when successive baskets do not contain complete reward thresholds
  • Fixed - fixed issue with basket voucher distribution when basket voucher and percentage discount voucher were being redeemed together
  • Fixed - fixed issue with checking active campaigns in basket campaigns
  • Fixed - fixed issue with content zone filtering not working properly in get-content-page
  • Fixed - fixed issue with content zones returned when applying business filter
  • Fixed - fixed issue with ordering business by distance in get-businesses
  • Fixed - fixed issue with recurrence logic in purchase count campaign
  • Fixed - fixed issue with transactions when using update_if_exists flag in add-user
  • Fixed - fixed rounding issue when meal deal and free basket competition are used at the same time
  • Fixed - issue with BasketCampaign fixed_monetary_discount and add-basket when item_original_price is missing.
  • Fixed - issue with returning only active campaigns when searching
  • Fixed - issued competition vouchers for later use now indexed in get-basket-price call

1.5.3 - Multiple updates

  • Added - entries wallets for competitions
  • Improved - made chain_id parameter as mandatory with admin authentication in claim-voucher and unclaim-voucher endpoints for requests >= 1.5.3
  • Improved - extended Competition campaign functionality by adding budget and budget-based probability calculation
  • Improved - added call processing queuing to assigning a member_number in MyPrice App
  • Improved - added a minimum basket value for instant win competitions
  • Improved - added business_region and business_format as campaign assignment fields
  • Improved - added entryreference variable to transaction messages
  • Improved - added new user identifiers to claim-voucher and unclaim-voucher
  • Improved - added segment checking to birthday campaign issue script
  • Improved - added several variables to transaction messages: firstname, itemsneeded, value, eligibleitems
  • Improved - added total count to get-businesses response
  • Improved - allow increased competition budget amounts
  • Improved - competition campaigns decide whether to award wins based on supplied basket timestamp rather than processing timestamp
  • Improved - extended matching item campaign to issue points on value of basket if a basket contains a defined number of matching items
  • Improved - extended user-wallet-ledger to include branch business ID in the response
  • Improved - improved admin user authentication permissions-checking and input validation
  • Improved - improved user/customer synchronisation with Garden Connect API
  • Improved - removed member_number from user on obfuscation
  • Improved - removed redundant user eligibility check from event handling in birthday campaign
  • Improved - the way in which creating a dummy email address works
  • Fixed - edge-case in promotional basket reward calculation
  • Fixed - rounding issue in BasketCampaign
  • Fixed - issue with promotions display for wallet and points wallet
  • Fixed - parameter name issue when searching for businesses
  • Fixed - issue where user’s dummy email address could be changed inadvertently
  • Fixed - reintroduced missing log_message in user_purchase_progress points and wallet ledger entries and notifications
  • Fixed - stop returning unredeemed competition vouchers in response to get-basket-price

1.5.2 - Multiple updates

  • New - added competition campaigns and functionality
  • New - added claim-vouchers endpoint to allow claiming (and optional locking) of multiple vouchers in a single call
  • New - added new business endpoints get-business, get-businesses, delete-business
  • New - users can now be created in add-user without requiring an email address or any other parameters
  • New - added third party id to voucher object when chain configuration is set to allow third party id
  • Improved - added default 400 HTTP response code for certain older API errors when request version is >= 1.5.2
  • Improved - added title to vouchers_created section of response to add-basket, get-basket-price endpoints (backwards compatible to release 1.4.8)
  • Improved - removed text from vouchers_created section of response to add-basket, get-basket-price endpoints
  • Improved - get-basket-price, add-basket and ARTS POSLog endpoints now return a user_not_found warning if a user identifier is passed, but the user is not found (backwards compatible to release 1.0.0)
  • Improved - added is_recurring to campaign fields in endpoint responses
  • Improved - added authentication_point_identifier as parameter for delete-user endpoint
  • Improved - member_number field can now be updated by end users in alter-user endpoint
  • Improved - added business_format to business endpoints
  • Improved - added update_if_exists facility to add-business endpoint
  • Improved - better validation in all business endpoints
  • Improved - allow birthday, loyalty and wallet campaigns to use campaign assignments
  • Improved - added return_reclaims_earned_rewards flag to allow a campaign to control whether rewards are reclaimed in a return
  • Improved - added warning in basket call responses if a user is submitted but not found
  • Improved - added template-based transaction messages to created vouchers and purchase progress in get-basket-price and add-basket responses
  • Improved - added campaign-level configuration flag, allows_end_user_to_claim_voucher to control whether an end user can claim a voucher
  • Improved - added purchase progress created during a campaign to output of get-basket-price and add-basket endpoints
  • Improved - delete-user API endpoint now allows use of authentication_point_identifier parameter to identify user
  • Improved - Garden Connect/Green Solutions integration now supports adding users with password
  • Improved - birthday campaigns now fully support user segments
  • Fixed - issue with subscription campaign unsetting Stripe price ID
  • Fixed - issue where percentage basket vouchers regenerate on partial redemption in certain circumstances
  • Fixed - issue where empty voucher distribution amount in distribution override caused erroneous total price calculations
  • Fixed - bug where duplicate products were being created in some add-basket requests
  • Fixed - issues with synchronisation of Shopify customer note field with user birthday
  • Fixed - minor issue with user CSV importer user recognition
  • Fixed - 500 error generated incorrectly in add-user when not setting a username value and update_if_exists is set to true
  • Fixed - issue where product price stored in the database influenced basket campaign promotional and other pricing in get-basket-price and add-basket endpoints
  • Fixed - issue where voucher was applied to basket in get-basket-price and add-basket endpoints when no voucher distribution was applied to the voucher
  • Fixed - issue where progress was not calculated correctly with some spend and earn campaign assignments
  • Fixed - memory exhaustion error when loading large numbers of product variants in some API endpoints
  • Fixed - issue where user’s dummy email address could be changed inadvertently

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 and add-basket calls in order to allow profit margin calculations and analytics sliced by various parameters such as store, product, user segment etc
  • Improved - get-basket-price, add-basket and ARTS POSLog endpoints allow item price rounding to 4 decimal places instead of the previous 2
  • Improved - upgraded unit price rounding to max 4 decimal places in receipt line items
  • Improved - remove campaign information from the get-user-vouchers response
  • Improved - added a campaign_types filter to the get-campaigns endpoint
  • Improved - added programme_opted_in to business
  • Improved - added created_date and last_modified_date to user in responses to certain calls
  • Improved - standardised custom headers to use X-Spaaza- prefix
  • 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 and claim-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 and excluded_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 in get-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 if vouchers_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 incorrect voucher_amount values for vouchers which had been claimed and processed by get-basket-price, but not yet redeemed
  • Fixed - issue displaying content campaigns in get-campaigns
  • Deprecation notice - All non-voucher fields (promotions and wallet) to be removed from version 1.5.1 of get-user-vouchers

1.4.11 - Update to get-campaigns

  • Switch default behaviour of exclude_inactive in the get-campaigns API endpoint. Previously, inactive campaigns would be included in the API response by default unless the exclude_inactive parameter was set to true. Now, inactive campaigns are excluded by default unless exclude_inactive is set to false.

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 replace shopper object with user object.

1.4.8 - Additions to responses to get-basket-price and add-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 in user_info response object to YYYY-MM-DD.

1.4.5 - Updates to add-basket and get-card

  • Update add-basket response to include item_original_price in request object for basket item and to display voucher_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 return result_type of get-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 as cashback within the promotions block.

1.4.3 - Update currency display in get-card response

  • Returns a standard currency object across all campaign types within get-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 and add-basket
  • Update parameters to allow multiple parallel wallets
  • Previous name of basket_vouchers array in response JSON of get-vouchers changed to vouchers.

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 names
  • add-basket endpoint request and response JSON updated to change parameter names
  • lock-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.