32 posts tagged with "api"

Additional API features, improvements and fixes that shipped to production in mid June 2026, on top of the earlier early June 2026 release.

• Added max_basket_discount_amount campaign field, allowing a per-voucher cap on the discount value of percentage basket vouchers at redemption time. The cap is enforced per voucher during get-basket-price and add-basket.
• Added new admin permission fields permission_analytics, permission_export, and permission_segment_query on add-user, alter-user, and permission-related endpoints, enabling more granular access control for admin accounts.
• Added created_date and last_modified_date as sort parameters for the Business and AllowedIpRange resources in the Resources API.
• Changed percentage basket voucher application on chains that allow double discounting: get-basket-price and add-basket now apply all eligible campaign-level standalone percentage basket vouchers by threshold allocation — sorted by campaign reward_priority, then cap-aware delivered discount for same-priority vouchers, then created_date — instead of keeping only the single best percentage voucher. The max_basket_discount_amount cap applies per voucher.
• Changed voiding/cancelling a transaction via an empty get-basket-price (no items and basket_total_value 0) to also unlock the shopper's standalone vouchers: any claimed, non-expired voucher locked to the same retailer_basket_code / voucher_locking_code now has its lock cleared, not only on-the-fly basket campaign vouchers.
• Improved event handling so that deferred events (such as OTP SMS notifications) are no longer triggered when the API request that staged them fails.
• Improved get-basket-price to no longer return misleading warnings for auto-loaded vouchers that do not match campaign spend-assignment parameters.
• Fixed an issue where voucher key generation under high concurrency could produce duplicate keys.
• Fixed a get-basket-price error that occurred when the basket had no items and the user held vouchers from inactive campaigns.

Additional API features, improvements and fixes that shipped to production in early June 2026, on top of the earlier mid May 2026 release.

• Added get-campaigns support for JWT-based shopper authentication, extending the JWT auth support introduced in version 1.6.4 to campaign listing.
• Added Chain resource to the Resources API with GET, PUT, and PATCH support, including nested allowed_ip_ranges and a new standalone AllowedIpRange resource.
• Added chain-level configuration flag for partial-redemption voucher regeneration, allowing chains to control whether partially-redeemed vouchers are automatically regenerated with the remaining value.
• Added chain-level basket campaign assignment restriction settings.
• Added composable reward-method voucher-shaping configuration fields: voucher_claimed_by_default, voucher_expiry_seconds / voucher_expiry_date, and spend_on_promotional_items, enabling fine-grained control over voucher behavior at the reward-method level.
• Added reward-method-level return_reclaims_earned_rewards field for wallet_contribution reward methods, allowing chains to prevent clawback of earned purchase progress when the earning purchase is returned.
• Changed add-user and alter-user to no longer automatically trigger phone number verification SMS; clients must now explicitly initiate verification through the phone verification flow.
• Improved call-processing error handling across multiple API endpoints to return structured API error responses for concurrent request timeouts.
• Improved segment CSV exports to handle larger datasets without timing out.
• Improved task-based data exports to exclude deleted users.
• Improved Spotler webhook integration with updated payload format.
• Fixed cashback campaign calculation that incorrectly double-subtracted voucher discounts from item prices.
• Fixed handling of deleted campaign restrictions.

Additional API features, improvements and fixes that shipped to production in mid May 2026, on top of the earlier early May 2026 release.

• Added basket-level discount calculation and percentage-based basket voucher support for composable campaigns, extending composable campaigns to handle basket-discount reward flows.
• Added win_chance configuration to composable campaign reward methods, enabling probabilistic reward issuance so that only a configured percentage of interactions trigger a reward (for example a 5% chance per basket).
• Changed get-user-vouchers to return voucher campaign details in a nested campaign object for API version 1.6.5 and above, including bounded campaign assignment rows with assigned business details, assignment_count, assignment_count_by_type, and assignment_types_excluded fields. Older versions keep the legacy flat campaign_* fields.
• Improved API response times for basket endpoints (get-basket-price and add-basket) through caching improvements.
• Improved create-voucher with concurrency protection to prevent duplicate voucher creation from simultaneous requests.
• Improved robustness of API requests involving segment lookup through improved retry logic.
• Fixed campaign segment-restriction handling so that campaigns with segment restrictions correctly fail closed.
• Fixed get-tags, get-assigned-groups, and get-reward-methods endpoints returning server errors instead of proper API error responses when the chain_id parameter is missing.

Additional API features, improvements and fixes that shipped to production in early May 2026, on top of the earlier mid April 2026 release.

• Added stateless JWT-based shopper authentication, allowing chains to configure trusted JWT issuers via jwt_jwks_url, jwt_issuer, and optional jwt_audience fields on alter-chain and get-chain. Shopper JWTs are validated using JWKS with automatic key-rotation support, and alter-user enforces an explicit customer_profile.write scope when called with JWT authentication.
• Added a fixed_value calculation method to composable campaign reward methods, alongside the existing basket-value and items-value methods.
• Added a context field to composable campaigns, with context-based filtering of available restrictions and reward methods.
• Changed composable campaign budget and usage-limit configuration to be set at the reward-method level rather than the campaign level.
• Changed admin and user permission payloads so that the legacy empty businesses block is no longer included in auth/login, auth/session, auth/get-user-permissions, and get-user responses for API version 1.6.4 and above. Older versions still return businesses: null for compatibility.
• Improved phone-number verification so that re-submitting the same phone number on alter-user or add-user preserves the VERIFIED status instead of resetting to VALIDATED, avoiding unnecessary OTP re-verification.
• Improved phone-number validation so that invalid phone numbers submitted via legacy API versions (below 1.6.1) are now stored with INVALID status instead of UNCHECKED, giving better data visibility.
• Improved Stripe subscription handling to fix cancellation webhooks silently failing when a subscription's annual expiry had passed, and to prevent duplicate Stripe subscriptions being created by failed renewal retries.
• Fixed composable campaign segment-restriction evaluation returning an incorrect type when the segment response was empty, which could cause campaigns with segment restrictions to behave unexpectedly.

Additional API features, improvements and fixes that shipped to production in mid April 2026, on top of the earlier late March 2026 release.

• Added phone-number verification via SMS one-time passcode (OTP) during user signup and phone-number change, controlled by a chain-level setting.
• Added a reward object to the interact-campaign response when a reward is issued, so clients can display the reward that was won (for example in scratch-card-style flows).
• Added content pages to the Resources API via the /resources/content_pages resource, including filtering by name, a parent link for page hierarchy, and display_name, order and active/inactive support.
• Changed add-product and add-product-variant (and the related product and product-variant importer scripts) so that price is now optional; products and variants can be created without a price where one is not yet known.
• Fixed a case where email-marketing-consent state from Shopify customer payloads was not recognised consistently across webhook and GraphQL shapes, which could leave subscribed customers stored as unsubscribed.
• Fixed basket-campaign distribution when a basket_fixed rule is not set, so distribution totals are calculated correctly for these campaigns.
• Fixed a case where a campaign with only spend assignments would incorrectly allow every basket item to qualify for the reward when no items matched the spend assignments.

Additional API features, improvements and fixes that shipped to production in late March 2026, on top of the earlier mid-March 2026 release.

• Added a new composable campaign type that combines configurable reward-handling behaviour (independent or random_draw, for example competition-draw rewards), reward methods with their own restrictions, usage limits and usage costs, and voucher-style rewards. Composable campaigns can also be triggered via interact-campaign for scratch-card-style flows.
• Added a rewards_handling_behaviour field (independent/random_draw) on composable campaigns.
• Added a usage_cost restriction on composable campaigns so that a wallet balance is deducted per interaction.
• Added usage_limit and selection fields on reward methods, including competition-style random-draw weighting.
• Added reward-method-level restrictions (currency, business, basket_item) so that spend-context restrictions can be applied directly to a reward method.
• Added an honour_voucher reward-method type with honour_code configuration.
• Added member-number-range fields to chain endpoint responses.
• Added a chain-level setting that controls how long after a user is created a referral_code can still be applied to trigger referral-campaign rewards.
• Added a new auth/apply-referral-code endpoint so that an existing user can submit a referral code after signup (within the chain's configured submission window).
• Added explicit is_default create and alter handling to loyalty campaigns, with the API enforcing that only one active default loyalty campaign can exist per chain.
• Changed loyalty-level-change side effects so they are only triggered for the campaign that owns the progress entry, preventing duplicate side effects when a chain has multiple active loyalty campaigns.
• Improved database performance for voucher and voucher-distribution reporting through additional database indexes.
• Fixed min_earn_quantity handling for fixed-monetary and quantity-unit basket campaigns so that an empty min_earn_quantity no longer triggers a type error, and a submitted value of 0 is preserved rather than silently coerced to 1.
• Fixed claim-basket so that campaign barcode assignments are preloaded consistently with add-basket, ensuring only items matching a campaign's barcode-assignment list qualify for rewards.
• Fixed delete-voucher and expire-voucher so they no longer delete or expire a voucher that has already been redeemed (previously this could incorrectly restore wallet balance for wallet-campaign vouchers).

Additional API changes, improvements and fixes that shipped to production in mid-March 2026, on top of the earlier early March 2026 release.

• Improved phone-number validation so that certain additional South African number prefixes (+27500, +27501, +27502) that were previously rejected as invalid are now accepted.

API changes, improvements and fixes that shipped to production in March 2026, on top of the earlier late February 2026 release.

• Changed admin-user handling across add-user, get-user, alter-user, and delete-user so admin operations are strictly scoped to the requested chain: existing admin users can be granted permissions for an additional chain via a cross-chain upsert, duplicate adds for the same chain return user_already_exists, chain-scoped super-users can only see and alter other admins within the requested chain, and delete-user removes only the requested chain's permissions before fully deleting an account once no permissions remain.
• Changed alter-user admin handling so admins cannot alter their own permission fields or login_2fa_exempt flag (self-escalation protection).
• Changed chain endpoints (including alter-chain) so image_url, receipt_logo_url, and password_reset_url can be cleared by passing an empty string or null.
• Improved basket campaign reward-exclusion performance by caching and reusing campaign-type information, reducing repeated campaign lookups during reward calculation on larger baskets.
• Fixed a Shopify integration issue where an empty username in an alter-user request could null out the customer's Shopify email address and disable the Shopify customer account.

Additional API features, improvements and fixes that shipped to production in late February 2026, on top of the earlier February 2026 release (1.6.3).

• Added support for a product unit field via add-product, returned by the product endpoint (for example g, l, or item).
• Added a chain-level option to exclude rewards on basket items that have already been discounted by a basket campaign.
• Added a chain-level multiplier for scaling competition win rates per chain or region.
• Added a till_code field on baskets, exposed through basket and transaction documents.
• Changed basket campaigns so they no longer require campaign rules; rule-free basket campaigns now qualify and apply implicitly.
• Changed claim-basket so admin users and privileged-auth requests are no longer subject to the anonymous-basket claim rate limit.
• Changed the product variant importer so it accepts either owner_code or product_variant_owner_code as input, and allows a blank owner code.
• Changed the Resources API so mutating requests (POST, PUT, PATCH) must use a JSON object body, lookups or deletes with empty identifiers are rejected, unknown resource types fail deterministically, and singular and plural routes no longer accept each other's reserved parameters.
• Changed the Resources API Business resource so business_id is no longer globally required in its OpenAPI schema.
• Improved voucher redemption_count so it is normalised consistently across receipts and indexing (taking min_earn_quantity into account).
• Improved database performance for user phone number lookups.
• Fixed matching item threshold campaign reward distribution across multiple basket items so the correct remaining quantity is used.
• Fixed get-webhooks and get-webhook so webhook secrets shorter than three characters are obfuscated correctly in API responses.
• Fixed campaign responses so minimum_matching_item_value is returned as null (rather than 0) when the value is unset.
• Fixed an authentication issue affecting user-wallet-ledger for user and Shopify authentication.
• Fixed Stripe subscription webhook handling so the interaction result is captured and reported when a subscription interaction does not complete.

• Added phone number validation and duplicate checks in add-user and alter-user endpoints.
• Added composable campaign and reward method foundations for modular campaign configuration.
• Added location search for the Resources API Business resource.
• Added text search support across multiple properties for get-businesses and the Resources API using search[*] syntax.
• Added task-triggered campaign support.
• Added spend basket-level campaign assignments.
• Fixed add-user so admin user creation now works correctly when an end-user with the same username already exists in the chain.
• Changed alter-user so API version 1.6.3 and above requires user_id when updating admin users by username.
• Improved alter-user so username clash checks now run in the target user's app when both user_id and username are supplied.

• Added - Change log added to Resources API for tracking audit history of entity changes with JSON diffs (API version 1.6.1+)
• Added - redemption_count field to UserPurchaseProgress for basket reward tracking
• Added - allowed_business_formats field to Chain model for business format restrictions
• Improved - Progress campaign reward limiting now caps rewards given within single transaction
• Improved - Rounding strategy validation for MatchingItemCampaign ensures consistency with wallet rounding rules
• Improved - Voucher locking behavior and basket campaign discount application
• Improved - Mobile pass configuration standardization (External dependency: iOS URL records need updating from s3:// to https://)
• Improved - Database performance for RFM calculation
• Fixed - Bug where basket campaign discount not applied when voucher locked in different campaign
• Fixed - Intra-transaction limiting of progress awards for Progress campaigns
• Fixed - Inactive campaign assignments now properly handled when redeeming vouchers

• Added - get-campaign-group endpoint to retrieve a single campaign group by ID
• Added - Resources API (beta) documentation providing RESTful access to (initially) Business and Voucher resources with OpenAPI compliance
• Improved - business search results in get-businesses endpoint now ordered by relevance when filtering by text search
• Improved - faster response times for campaigns and basket endpoints through various database optimisations
• Improved - voucher distribution field in get-basket-price and add-basket endpoints now includes item quantity on which the voucher was distributed
• Improved - campaign assignment group name maximum length increased from 16 to 64 characters
• Improved - Klaviyo integration supports Klaviyo "events" and "profiles" APIs instead of deprecated "track" API
• Fixed - issue where reward_priority field could not be set to 0 in alter-campaign and add-campaign endpoints
• Fixed - issue with order_by parameter in get-campaigns endpoint not being applied correctly
• Fixed - issue where count of campaign rewards used was incremented even when voucher was not redeemed in add-basket request

• Added - get-campaigns now supports filtering on business_owner_code campaign assignments
• Improved - get-campaigns endpoint now supports multiple filters simultaneously
• Improved - added customisable voucher locking period in get-basket-price request
• Fixed - issue where Cashback ("Spend and Earn") Campaign with no recipient wallet caused an error in get-basket-price and add-basket endpoints

• Added - 2-Factor Authentication (2FA) for admin login
• Added - campaign group filter to get-campaigns endpoint to allow filtering campaigns by their campaign group
• Added - pagination is now available for results in the get-campaign-groups endpoint
• Added - the ability to use multiple filters at the same time in get-campaigns endpoint
• Added - a customisable voucher locking period in get-basket-price request
• Added - user password reset functionality for Shopify customers (in the case of a Shopify integration)
• Improved - remove rewards on subscription cancellation in case of Stripe subscription integration
• Improved - zones and items are now optional in alter-content-page endpoint
• Improved - start and end dates are now optional in campaign and campaign-group endpoints
• Improved - add-campaign and alter-campaign performance improvements
• Improved - campaign group information is now shown in voucher distribution in get-basket-price and add-basket responses
• Improved - user indexing performance
• Fixed - race condition on auxiliary_identifier parameter when creating a user in Spaaza based on a Shopify customer webhook

• Added - added add-note, get-notes, delete-note endpoints to manage Note objects (these endpoints are restricted to admin authentication)
• Added - added get-content-pages and delete-content-page endpoints to manage content pages
• Added - Added opt_in_secondary_last_modified_date to a user, which is a datetime field that records the last time opt_in_secondary date changed
• Added - added non-payment error response to API to indicate when Spaaza customers are in payment default and cannot use the API
• Added - it is now possible to configure an optional maximum_basket_total_value_spend in a campaign - a maximum basket total value for a reward to be redeemed in a basket
• Added - it is now possible to configure an optional maximum_basket_total_value_earn in a campaign - a maximum basket total value for a reward to be earned
• Added - the add-basket and get-basket-price endpoints can now override the campaign redemption grace period. By specifying a redemption grace period in a specific basket, the campaign's default grace period can be overridden
• Added - the alter-chain and get-chain endpoints can now set a chain redemption grace period, which is the number of hours during which a campaign's vouchers can still be redeemed correctly after the active_date_until has passed
• Added - user authentication against the Shopify API is now supported, allowing end-users to authenticate against the Shopify API using their Spaaza credentials, such as when using the Spaaza whitelabel mobile app
• Added - issue a reward when a customer subscription renewal is received via a Stripe webhook
• Improved — improved retry handling when making calls to external APIs such as Magento 2, Green Solutions and other providers
• Improved - it is now possible to apply basket value restrictions (maximum_basket_total_value_spend and maximum_basket_total_value_earn) to matching item campaigns, allowing for more control over the redemption process
• Improved - improvements in content page campaign handling
• Improved - it is now possible to restrict redemption of a competition grand prize to the store in which the prize was issued
• Improved - updates to IOS mobile pass wallet handling
• Improved - completed Shopify API communication migration to Shopify GraphQL admin API
• Improved - improvements to win distribution time algorithm for store-budgeted competition campaigns
• Improved - performance improvements in competition budget checking when issuing instant win vouchers
• Improved - webhook handling for Stripe subscription features
• Improved - event pipeline performance improvements for wallet mutation events
• Improved - locale (language) field is now synchronised between Spaaza user account and Shopify customer account, allowing for better localisation of content and campaigns
• Improved - performance when user member number updates take place
• Improved - issue-avoidance when processing simultaneous duplicate webhooks received from Shopify
• Fixed - issues in Shopify account activation flow
• Fixed - bug in matching non-product campaign assignments
• Fixed - issue with missing title when creating Shopify discount code for wallet voucher
• Fixed - issue with unhandled exception when no response is received from Green Solutions (formerly Garden Connect) API
• Fixed - issue with voucher redemption after campaign active date has passed
• Fixed - issue where wallet mutation event was not dispatched correctly when a customer used points to receive a reward
• Deprecated - the user-specific notes field has been replaced by the new Note object in the add-note, get-notes and delete-note endpoints, which allows for more flexible and structured note management. The notes field will be removed from the response to the get-card endpoint in version 1.6.0.

• 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.

• Added - per-store budgets and wins distribution for competition campaigns, ensuring fair distribution of rewards across stores
• Improved - competition campaigns now limit the number of wins per store per day and distribute win opportunities throughout the day

• Improved - after a successful Stripe payment notification webhook is received, Spaaza updates the (external) identity handler after user opt_in_secondary is set
• Improved - when nullifying user username in alter-user, use a chain's dummy email domain, if available, to set a dummy email address
• 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 - the get-campaigns endpoint now supports pagination for API requests.

• 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 parameter_mismatch warning in basket endpoints when sum of item_price amounts for items does not match basket_total_price value
• Improved - return a warning in basket endpoints when a returned item cannot be matched to an original purchase transaction

• 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 - added address fields to Profile Completion campaign
• Improved - excluded delete campaigns from campaign groups in responses
• 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. (versions >= 1.5.4)
• Fixed - fixed issue creating duplicate rewards in Profile Completion campaign
• Fixed - fixed issue with checking active campaigns in basket campaigns
• Fixed - fixed issue with transactions when using update_if_exists flag in add-user