Ecommerce Best Practice Guide

🚧
The API tools provided for your ecommerce integration with Springbig are referred to as POS API. These tools serve a dual purpose, being utilized not only by point-of-sale systems but also by ecommerce clients

Introduction

Springbig provides an integration API intended for use by POS and e-commerce applications. This easy-to-use API is client-platform independent and allows the client software to access the full earning and redemption capabilities of the platform.

Security and Endpoint URLs

The API uses TLS encryption and authentication via a Client specific API key. The keys provided by Springbig are different for test and production environments.
Springbig provides different URLs for the API calls made to test and production environments. Corresponding API keys have to be used with this.

Robust Syncing

The API practices described here are intended to produce maximum consistency of data, meaning that both the customer and transaction data are consistent between the Ecomm and Springbig platforms.

Identifying the Merchant in API Calls

As you can see in the pseudocode fragments below, there is no need to pass the merchant ID via the API. The merchant ID is implicit in the authentication token that is provided by
Springbig and included in each call.

Main Interaction of the Ecomm with Springbig

The typical interactions (Scenarios A-E) below are expressed in pseudocode in order to
enhance readability and demonstrate interaction with Springbig from the perspective of a typical Ecomm platform. Translation to the language of choice should be straightforward. The following interactions are covered:

Posting a customer and their attachment of consent to loyalty, sms, or email
1. 1. ECOMM_CUSTOMER_ID = pos_user
Modifying customer data on the Springbig platform when their profile is modified in the Ecomm.
Export of customer data from POS to Springbig
1. customer sync
Looking up available rewards and reward redemption
Looking up available offers and offer redemption
Abandoned cart communication tools

Scenario A – Posting a customer after that customer signs up for the loyalty and marketing program

This interaction occurs during customer checkout at the conclusion of the visit. The
customer has an opportunity to sign up for the loyalty and communications program. There should be a consent-captured

API endpoint for sharing the customer

API endpoint for sharing the customers consent (Optional)

🚧
Attachment endpoint (Optional)
The member attachment endpoint, which is used to collect the customer signature, uses the Springbig member ID. As opposed to other endpoints referencing the pos_user (clients unique identifier of the member

// Customer enters the checkout phase
.
// Check if the customer exists in Springbig database. If yes, update with latest
// data. If not, create the customer:

Customer Data = GetCustomer( ECOMM_CUSTOMER_ID ); 

If( Customer exists )
	{
		// update Springbig with latest customer data
		PutCustomer( ECOMM_CUSTOMER_ID, ECOMM_CUSTOMER_DATA[] );
	}
else
	{
		// create customer in Springbig database
		PostCustomer( ECOMM_CUSTOMER_ID, ECOMM_CUSTOMER_DATA[] );
	}

// customer accepts consent to opt into loyalty, sms, email
// share attachment that customer opted in

PostAttachment( SPRINGBIG_MEMBER_ID, Attachment_data );

📘
Member merging
A Member object in springbig can have many profiles. A profile will merge into the Member object based on the following matching criteria

pos_user

phone number

email

Scenario B – Modifying customer data on the Springbig platform when their profile is modified in the Ecomm

This interaction occurs every time a customer profile is modified in the POS

API endpoint for updating customers

// Customer profile is modified in the POS
.
// Check if the customer exists in Springbig database. If yes, update with latest
// data. If not, create the customer:

CustomerData = GetCustomer( ECOMM_CUSTOMER_ID ); 
If( Customer exists )
	{
		// update Springbig with latest customer data
		PutCustomer( ECOMM_CUSTOMER_ID, ECOMM_CUSTOMER_DATA[] );
	}
else
	{
		// create customer in Springbig database
		PostCustomer( ECOMM_CUSTOMER_ID, ECOMM_CUSTOMER_DATA[] );
	}

Scenario C – Export of customer data from Ecomm to Springbig

This interaction is needed at the time Ecomm integration between a merchant and Springbig is turned on. The following points should be noted:

API endpoint for syncing customer or transaction data

This is not a general-purpose interaction and therefore access to this functionality should not be available to the normal budtender personnel, possibly relegated to Ecomm admin functions.
It is important that the export be executed prior to the integration being turned on in order to make sure that the customers who exist in the Ecomm also exist in the Springbig database, in order for them to be available for campaigns.
This function is idempotent, meaning that it can be run any number of times and at any time.
This is a historical member sync. All existing members should be shared using the batches endpoint to post it all in one request.

// The Customer Export function is initiated by POS administrator, at minimum
// prior to turning on integration and any time thereafter, whenever a customer
// “sync” might be desirable

for( each customer in the POS database ) do

// create customer in Springbig database
PostCustomer( ECOMM_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
// post the transaction, referencing the customer:
PostTransaction( ECOMM_TRANSACTION_ID, POS_CUSTOMER_ID, Transaction_data );

Scenario D – Looking up Available Rewards and Reward Redemption

Each loyalty program has one or more configured rewards. Each of these has four elements:

API endpoint to retrieve and redeem rewards

Reward Id which uniquely identifies the reward
Reward Description, which is a human-readable description of the reward
Reward Reward value, which represents the number of points required to redeem the reward
Reward discount type, which represents the discount method (Ie: % or $ type off)
Reward discount amount, which represents the value of the discount (ie: 15 % off)
Reward Pos discount id, which is a merchant-configured string that identifies the reward to the Ecomm
- this is only used when an ecomm has the functionality to handle internal discount configuration settings. If so, this discount id can be used to link the springbig reward to the ecomm discount. In the API reward response, the meta field represents the value of the pos discount id.

📘
Discount application
It is advised for ecomm's to use the discount amount and discount type of a reward to apply the discount as a line item to the cart.

Redemption of a reward is not mandatory, even though a customer may have accumulated a sufficient point balance.

API Endpoint to process a reward redemption

Springbig can handle multiple reward redemptions. The decision to allow stacking rewards is ultimately up to the ecommerce provider.

// Get rewards configured in the merchant’s loyalty program

CustomerData = GetCustomer( ECOMM_CUSTOMER_ID ); RewardData = GetRewards( );

// Display all rewards:

for( each reward x in RewardData )
{
		Display RewardData[ x ].Description, RewardData[ x ].PointCost
}

// Display all rewards that can be redeemed by the customer:

for( each reward x in RewardData ) do
		if( CustomerData.PointBalance >= RewardData[ x ].PointCost
		Display RewardData[ x ].Description, RewardData[ x ].PointCost );
done

// Customer selects a reward x to be redeemed and redemption is performed

// RewardData[ x ].DiscountAmount and RewardData[ x ].DiscountType should be used to apply the discount to the cart

RedeemReward( ECOMM_CUSTOMER_ID, RewardData[ x ].Id );

Scenario E – Looking up Available Offers and Offer Redemption

A loyalty program may have one or more configured rewards. Furthermore, offers are not necessarily applicable to all customers, hence the customer ID must be specified in order to retrieve the available offers. Each offer has four elements:

API endpoint to retrieve a member's available offers

Offer Id which uniquely identifies the offer
Offer Description, which is a human-readable description of the reward
Offer ExpirationDate, which may be blank, in which case the offer does not expire
- if an offer is expired it will not be included in the API response
Offer Redemptions Available, which is the amount of times that this offer can still be redeemed
- if an offer has 0 redemptions available it will not be included in the API response
Offer discount type, which represents the discount method (Ie: % or $ type off)
Offer discount amount, which represents the value of the discount (ie: 15 % off)
Offer Pos discount id, which is a merchant-configured string that identifies the offer to the POS

📘
Discount application
It is advised for ecomm's to use the discount amount and discount type of an offer to apply the discount as a line item to the cart.

Redemption of an offer is not mandatory, and should be selected by the customer

API Endpoint to process an offer by a member

// Get offers configured in the merchant’s loyalty program that are available
// to a specific customer

CustomerData = GetCustomer( ECOMM_CUSTOMER_ID );

// Check for applicability of customer offers to the current purchase and apply if
// not expired

for( each offer x in CustomerData.Offers ) do
	if(CustomerData.Offers [ x ].ExpirationDate > Now( ) AND AppliesToCurrentTransaction(CustomerData.Offers [ x ].PosCode ) == TRUE )
	{
		RedeemOffer( ECOMM_CUSTOMER_ID, OfferData[ x ].Id );
	}
done