Common Workflows

The Sparkfly POS API can be used in two different modes:

1. Automatic Offer Application. In this use case, the platform is configured to respond to a Transaction Query (status of codeEntry) with all possible offers to be applied, immediately. In this case, there is an assumption that if a coupon code or loyalty identifier is scanned, that all available offers should be applied as aggressively as possible. This is typically the best option when dealing primarily with one-time use coupon codes.
2. Manual Offer Selection. In this use case, it is expected that the caller will make multiple API calls to apply offers. When credentials are applied (via codeEntry status), offers will not be applied. The caller must break this process up over three API calls (credential validation, query offers, apply offers). This is typically the best option when dealing primarily with loyalty customers who may be picky about which offers they would like to use on any given visit, or may have large offer wallets consisting of dozens of available offers.

It is possible to use a combination of these workflows. For example, it is possible to treat one-time use coupons as "apply immediately" and digital offer wallet (or loyalty) as offer selection.

Workflow: Automatic Offer Application

In this use case, the platform is configured to respond to a Transaction Query (status of codeEntry) with all possible offers to be applied, immediately. In this case, there is an assumption that if a coupon code or loyalty identifier is scanned, that all available offers should be applied as aggressively as possible.

Typically, this involves the following API calls:

1. At the time a credential is entered, submit a Transaction Query with a status of codeEntry. The API will respond with an array of messages to display, offers to apply, and whether the supplied credentials were valid.
2. Any time the transaction is modified, re-submit the transaction, along with any currently applied credentials or offers via Transaction Query with a status of background.
3. When the transaction is finalized, typically following payment, submit the final transaction details, along with any applied credentials or offers, via Transaction Finalize with a status of closed.

Workflow: Manual Offer Selection

In this use case, it is expected that the caller will make multiple API calls to apply offers. When credentials are applied (via codeEntry substatus), offers will not be applied. The caller must break this process up over three API calls (credential validation, query offers, apply offers).

Typically, this involves the following API calls:

1. At the time a credential is entered, submit a Transaction Query with a status of codeEntry. The API will respond with an array of messages to display, offers to apply, and whether the supplied credentials were valid.
2. Any time the transaction is modified, re-submit the transaction, along with any currently applied credentials or offers via Transaction Query with a status of background.
3. When it is time to display a list of available offers for selection, submit a Transaction Query with a status of queryOffers. The platform will perform its normal validations, and reply with all available offers in the available_offers array.
4. Once the staff member (or end user) has selected which offer(s) to apply, submit the selected offers via Transaction Query with a status of applyOffers. When this request is sent, it should include the selected_offers array, which tells the platform which offers to apply. The platform will perform the necessary calculations and return the offers to apply in the add_offers array.
5. When the transaction is finalized, typically following payment, submit the final transaction details, along with any applied credentials or offers, via Transaction Finalize with a status of closed.

Aborted Transactions or Credential Removal

Regardless of the workflow used, at some point an integration will need to deal with the situation where a transaction in progress (i.e. a Transaction Query has been sent to Sparkfly but no Transaction Finalize) has been cancelled, or the applied credentials and offers have been removed. In this case, the integration should send a Transaction Void API call. This will release all associated locks for the transaction, and allow any offers that were applied to be available for other transactions.

It is the integration's responsibility to ensure that the credentials and any associated offers/discounts are removed from the transaction following a call to the Transaction Void endpoint.

Other Workflows

The user interface for your application, online ordering system, mobile app, or POS system may not fit the mold of these predefined workflows. The Sparkfly POS API is intentionally designed to allow for flexibility. It may be possible to use both workflows in different circumstances or combine them in creative ways.

As always, our team is here to support you through the integration process.