Documentation

POS Best Practice Guide

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 POS 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 POS 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 POS platform. Translation to the language of choice should be straightforward. The following interactions are covered:

  1. Posting a customer and their attachment of consent to loyalty, sms, or email
  2. Posting a POS transaction after checking that the customer exists on the Springbig platform.
    1. POS_CUSTOMER_ID = pos_user
    2. POS_TRANSACTION_ID = pos_id
  3. Modifying customer data on the Springbig platform when their profile is modified in the POS.
  4. Export of customer data from POS to Springbig
    1. customer sync
  5. Looking up available rewards and reward redemption
  6. Looking up available offers and offer redemption
  7. Points-for-Cash reward redemption (new)
  8. Collecting Springbig member sign ups (two-way integration)

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

🚧

Attachment endpoint

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( POS_CUSTOMER_ID ); 

If( Customer exists )
	{
		// update Springbig with latest customer data
		PutCustomer( POS_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
	}
else
	{
		// create customer in Springbig database
		PostCustomer( POS_CUSTOMER_ID, POS_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

  1. pos_user
  2. phone number
  3. email

Scenario B – Posting a POS transaction after checking that the customer exists on the Springbig platform

This interaction occurs during customer checkout at the conclusion of the visit API endpoint for posting visits

🚧

Transactions should only be shared once the payment is completed

// 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( POS_CUSTOMER_ID ); 
If( Customer exists )
	{
		// update Springbig with latest customer data
		PutCustomer( POS_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
	}
else
	{
		// create customer in Springbig database
		PostCustomer( POS_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
	}

// Post the transaction, referencing the customer:

PostTransaction( POS_TRANSACTION_ID, POS_CUSTOMER_ID, Transaction_data );

API endpoint for sharing transactions

Scenario C – Modifying customer data on the Springbig platform when their profile is modified in the POS

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( POS_CUSTOMER_ID ); 
If( Customer exists )
	{
		// update Springbig with latest customer data
		PutCustomer( POS_CUSTOMER_ID, POIS_CUSTOMER_DATA[] );
	}
else
	{
		// create customer in Springbig database
		PostCustomer( POS_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
	}

Scenario D – Export of customer data from POS to Springbig

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

API endpoint for syncing customer or transaction data

  1. 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 POS admin functions.
  2. 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 POS also exist in the Springbig database, in order for them to be available for campaigns.
  3. This function is idempotent, meaning that it can be run any number of times and at any time.
  4. This is a historical member and transaction sync. All existing members and previous transactions 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( POS_CUSTOMER_ID, POS_CUSTOMER_DATA[] );
// post the transaction, referencing the customer:
PostTransaction( POS_TRANSACTION_ID, POS_CUSTOMER_ID, Transaction_data );

Scenario E – 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 Pos discount id, which is a merchant-configured string that identifies the reward to the POS
📘

Pos discount id

The pos discount is configured by the merchant in our dashboard. It allows the POS to identify the reward, and apply the discount appropriately. In the API reward response, the meta field represents the value of the pos discount id.

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

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

CustomerData = GetCustomer( POS_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 ].PosCode can be used by the POS as an internal reward ID

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

Scenario F – 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 and redeem 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 Pos discount id, which is a merchant-configured string that identifies the offer to the POS
📘

Pos discount id

The pos discount is configured by the merchant in our dashboard. It allows the POS to identify the reward, and apply the discount appropriately. In the reward response, the meta field represents the value of the pos discount id.

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

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

CustomerData = GetCustomer( POS_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( POS_CUSTOMER_ID, OfferData[ x ].Id );
	}
done

Scenario G – Points-for-Cash Reward Redemption

A loyalty program may have one or more configured rewards, including a ‘points-for-cash’
(PFC) redemption. In a PFC redemption, a customer’s earned points are used for a discount that is applied against the current purchase, in either a POS or an eComm transaction.

In this scenario, the customer’s point balance may or may not be sufficient to pay for the entire purchase. The following pseudo-code fragment illustrates the POS or eComm logic at a high level:

API endpoints for points for cash redemption

// 1. Compute the transaction $ total as ‘TransactionTotal’
// 2. Retrieve the member’s point balance ‘PointBalance’
If( Points-for-Cash reward is configured in loyalty program )
{
	Compute discount dollars available, based on member’s point balance 
  If( Discount Dollars >= TransactionTotal )
	{
		Apply discount for whole transaction Member pays nothing
	}
	else
	{
		Apply partial discount against the transaction amount using all points available Member pays balance
	}
}
else
{
Post the redemption to Springbig, indicating the number of points redeemed and …
… the Reward ID (indicating a PFC redemption)
}

Points-for-cash reward is not available Consider redeeming other eligible rewards

Scenario H: Two-way integration

Incorporating a two-way integration involves gathering members who register on Springbig through various channels such as our join form. For point-of-sale systems, utilizing our member webhook events enables you to capture new loyalty sign-ups and stay informed about their SMS and email statuses.

Member webhooks

See our POS integration examples:

https://www.springbiguniversity.com/learn/dashboard?labels=%5B%22Integrations%22%5D&values=%5B%22POS%22%5D



Scenario I: Processing Refunds

Visits on Springbig are used to track customer spending behavior and serve as the source of truth for loyalty point calculation. Accurate visit data ensures proper reward issuance, customer segmentation, and reporting.

When submitting a refund to Springbig, the following rules and attributes must be applied:

Required Attributes

transaction_total

  • Must be sent as a negative value.
  • The value should follow the same pre-tax or post-tax logic used in the original sale.

pos_id

  • Must be a unique identifier for the refund transaction.
  • Should match the transaction identifier format used by the third-party system.

Invoice-Level Fields

Attributes such as:

  • final_total
  • sub_total
  • total_discount
  • (and any other invoice-related fields)

…should accurately reflect the refunded invoice values, following the same tax/discount logic as the original sale.

visit_details_attributes

Each refunded line item should contain:

  • quantity — negative integer representing the number of items being returned
  • price — negative value representing the per-item price being refunded
  • real — set to false to indicate this visit record is a refund and to ensure proper handling in visit-based loyalty programs

Updated 11 months ago

Did this page help you?