Provider Integration Endpoints

customers

list {object}

Yes

The list of customers identified in the loyalty system

customers.is_identified

boolean

Yes

The flag that represents if the customer was fully identified.

true - When the customer is identified and all customer information is present.

false - When multiple customers were found and an additional identifyCustomers request is required to obtain full customer information after a single customer is selected.

customers.balance

list {object}

BalanceResponseBody

No

The list of customer's loyalty balances. For example, points or visits.

customers.cards

list {object}

CardsResponseBody

No

The list of stored value accounts available for the customer

customers.identification_method

string (enum)

Yes

The method used to identify loyalty customer. The possible values are as follows: code, first_name, last_name, loyalty_card_number, email, phone_number, and coupon.

customers.information

object

InformationResponseBody

Yes

The customer's personal information.

customers.rewards

list {object}

Yes

The list of rewards available on the customer's balance.

customers.rewards[].id

string

Yes

The reward identification value

customers.rewards[].name

string

Yes

The reward name

customers.rewards[].balance

number

Yes

The reward quantity

customers.rewards[].amount

number

Yes

The reward discount amount

customers.rewards[].apply_automatically

boolean

Yes

The flag that identifies if the reward should be applied automatically.

customers.rewards[].status

string

No

The reward status

customers.rewards[].calculated_by

string

Yes

Indicates the party responsible for the loyalty rewards.

This should be set to "provider" when the loyalty rewards are calculated and validated by a loyalty provider.

This should be set to "client" when the loyalty rewards are calculated and validated by us.

customers.rewards[].program_id

string

No

The reward's program identifier

customers.rewards[].reward_type

string

No

The reward type

customers.rewards[].associated_points

string

No

The amount of points associated with the reward

customers.rewards[].promoted

boolean

No

The flag that identifies if the reward is promoted by a provider and should be shown in a "promoted" category.

customers.rewards[].promotion_type

string

No

The additional reward type. For example, Birthday Reward or Anniversary Reward.

customers.rewards[].qualified

boolean

No

The flag that identifies if the reward is applicable to the current order

customers.rewards[].expiration_dates

list {object}

Yes

The reward expiration dates.

 customers.rewards[].expiration_dates[].expiration_date

string

No

The reward expiration date

 customers.rewards[].expiration_dates[].points_quantity

string

No

The total number of rewards to expire

customers.rewards_data

object

Yes

The list of validated and declined rewards

customers.rewards_data.validated_rewards

list {object}

ValidatedRewardsResponseBody

Yes

The list of customer's rewards that should be added to the order automatically. 

customers.rewards_data.declined_rewards

list {object}

DeclinedRewardsResponseBody

Yes

The list of customer's rewards that did not pass the validation and is not applicable to the order. Typically, this is used in the single scan flow when the customer identification includes the reward that should be added to the order.

general

GeneralResponseBody

Yes

Includes the fields for the GeneralResponseBody

rewards_data

object

Yes

The list of validated and declined rewards

 rewards_data.validated_rewards

list {object}

ValidatedRewardsResponseBody

Yes

The list of customer's rewards that are validated and applicable to the order.

rewards_data.declined_rewards

list {object}

DeclinedRewardsResponseBody

Yes

The list of customer's rewards that did not pass the validation and are not applicable to the order.

general

GeneralResponseBody

Yes

Includes the fields for the GeneralResponseBody

rewards_data

object

Yes

The list of validated and declined rewards

rewards_data.redeemed_rewards

list {object}

RedeemedRewardsResponseBody

Yes

The list of successfully redeemed rewards.

rewards_data.declined_rewards

list {object}

DeclinedRewardsResponseBody

Yes

The list of customer's rewards that did not pass the validation and are not applicable to the order.

general

GeneralResponseBody

Yes

Includes the fields for the GeneralResponseBody

receipt

object

ReceiptResponseBody

No

The order receipt details

general

GeneralResponseBody

Yes

Includes the fields for the GeneralResponseBody

receipt

object

ReceiptResponseBody

No

The order receipt details

general

GeneralResponseBody

Yes

Includes the fields for the GeneralResponseBody

application_version

string

Yes

The version of Gift and Loyalty the company uses

clerk_id

string

Yes

The identifier for the employee who entered the transaction

date_time

string

Yes

The date and time of the transaction in YYYY-MM-DDTHH:MM:SS.001Z format

integrator_name

string

No

The name of the integrator connected to the transaction

integrator_type

string

Yes

The type of the integrator connected to the transaction

local_time

string

Yes

The time of activation in HH:MM:SS.001 format

local_date

string

Yes

The date of the transaction in YYYY-MM-DD format

terminal_id

string

Yes

The identifier for the terminal at the site

terminal_txn_id

string

Yes

The identifier used by the terminal to track the transaction

_id

string

Yes

The point of sale (POS) order identification

customer

object

Yes

The object containing the customer information

customer.loyalty_info

object

Yes

The customer loyalty information object

customer.loyalty_info.customer_id

string

Yes

The customer identification value

customer.loyalty_info.loyalty_card_number

string

Yes

The customer loyalty card number

customer.loyalty_info.offers

string

Yes

The the list of rewards that should be validated against the order

customer.loyalty_info.submit_order

object

No

The customer submit order object

customer.loyalty_info.submit_order.transaction_id

string

No

The transaction identifier of the submitted order

discount_info

object

Yes

The object with a list of all order-level discounts applied to the order. The applied loyalty discounts have a loyalty_info object.

discount_info.discounts

array

Yes

The list of all discounts applied to the order

discount_info.discounts[].amount

object

Yes

The discount amount

discount_info.discounts[].discount_code

string

Yes

The discount code

discount_info.discounts[].discount_definition_id

string

Yes

The discount definition identification value

discount_info.discounts[].distributed

boolean

Yes

The discount distribution flag

discount_info.discounts[].loyalty_info

object

No

The loyalty information details

discount_info.discounts[].loyalty_info.amount

string

No

The loyalty points amount

discount_info.discounts[].loyalty_info.apply_automatically

boolean

No

The flag that defines if the discount should be applied to the order automatically

discount_info.discounts[].loyalty_info.code

string

No

The loyalty information code

discount_info.discounts[].loyalty_info.program_id

string

No

The loyalty program identification value

discount_info.discounts[].loyalty_info.quantity_redeemed

number, string

No

The points quantity redeemed

discount_info.discounts[].loyalty_info.reward_id

string

No

The reward identification value

discount_info.discounts[].loyalty_info.reward_type

string

No

The reward type

discount_info.discounts[].loyalty_info.status

string

No

The loyalty status

discount_info.discounts[].name

string

Yes

The discount name

discount_info.discounts[].quantity

string

Yes

The discount quantity

discount_total

string

Yes

The total discount amount that is applied to the order

employee

object

No

The object containing information about the employee that is submitted with the redeemed reward

employee.id

string

No

The identification value for the employee who submitted the order

employee.name

string

No

The name of the employee who submitted the order

guest_count

string

No

The order guest count

items

array

Yes

The list of all items included in the order

items[].child_items[]

array

No

The list of inner items objects

items[].discount_info

object

Yes

The item-level discounts have "distributed":false and order-level discounts distributed among items have "distributed":true

The loyalty rewards have a loyalty_info object.

items[].discount_info.discounts[].amount

object

Yes

The discount amount

items[].discount_info.discounts[].discount_code

string

Yes

The discount code

items[].discount_info.discounts[].discount_definition_id

string

Yes

The discount definition identification value

items[].discount_info.discounts[].distributed

boolean

Yes

The discount distribution flag

items[].discount_info.discounts[].loyalty_info

object

No

The loyalty information details

items[].discount_info.discounts[].loyalty_info.amount

string

No

The loyalty points amount

items[].discount_info.discounts[].loyalty_info.apply_automatically

boolean

No

The flag that defines if the discount should be applied to the item automatically

items[].discount_info.discounts[].loyalty_info.code

string

No

The loyalty information code.

items[].discount_info.discounts[].loyalty_info.program_id

string

No

The loyalty program identification value

items[].discount_info.discounts[].loyalty_info.quantity_redeemed

number, string

No

The points quantity redeemed

items[].discount_info.discounts[].loyalty_info.reward_id

string

No

The reward identification value

items[].discount_info.discounts[].loyalty_info.reward_type

string

No

The reward type

items[].discount_info.discounts[].loyalty_info.status

string

No

The loyalty status

items[].discount_info.discounts[].name

string

Yes

The item discount name

items[].discount_info.discounts[].quantity

string

Yes

The item discount quantity

items[].is_bundle

boolean

No

The flag that identifies if the item is bundled

items[].item_type

string

Yes

The item type

items[].name

string

Yes

The item name

items[].order_item_id

string

Yes

The item order identification value

items[].price

string

Yes

The item price

items[].product_id

string

Yes

The product identification value

items[].quantity

string

Yes

The item quantity

items[].reporting_category

object

No

The item category object

items[].reporting_category.major_reporting_category

object

No

The item major category report

items[].reporting_category.major_reporting_category.external_category_id

string

No

The item major category report external identification value

items[].reporting_category.major_reporting_category.name

string

No

The item major category report name

items[].reporting_category.minor_reporting_category

object

No

The item minor category report

items[].reporting_category.minor_reporting_category.external_category_id

string

No

The item minor category report external identification value

items[].reporting_category.minor_reporting_category.name

string

No

The item minor category report name

order_number

string

Yes

The POS order number

order_type

string (enum)

No

The order type. Can be 'refund' order 'order'.

payment_info

object

No

The object containing an array of all payments

payment_info.change

string

No

The change amount

payment_info.payments[]

array

No

The list of payments used for the order

payment_info.payments[].account

string

No

The payment account

payment_info.payments[].amount

string

Yes

The payment amount

payment_info.payments[].card_brand_name

string

No

The card brand name used for payment

payment_info.payments[].code

string

No

The payment code

payment_info.payments[].name_on_card

string

No

The name on the card used for payment

payment_info.payments[].name

string

No

The payment name

payment_info.payments[].pay_type_id

string

Yes

The payment type identification value

payment_info.payments[].pay_type_name

string

No

The payment type name

payment_info.payments[].transaction_id

string, null

No

The payment transaction identification value

payment_info.tips

string

No

The amount of tips paid

payment_info.total

string

No

The total amount paid

subtotal

string

Yes

The order subtotal amount

tax_info

object

No

The object containing detailed information about the order taxes

tax_info.taxes

array

Yes

The list of all taxes applied to the order

tax_info.taxes[].amount

string

Yes

The amount of tax added

tax_info.taxes[].name

string

Yes

The tax name

tax_info.taxes[].tax_definition_id

string

Yes

The tax definition identification value

tax_info.total

string

Yes

The total tax amount

tax_info.total_exclusive

string

Yes

The total exclusive tax amount

time

object

Yes

The object containing the time the order was created and closed

time.created

string

Yes

The order creation timestamp

time.closed

string

Yes

The order closing timestamp

total

string

Yes

The order total amount

check_id

string

Yes

The customer's check identification value

code

string

Yes

The customer's identification

customer_id

string

Yes

A generic field for providing identifying information for the customer. It is used when the type of identifying information is not known.

email

string

Yes

The customer's email address

first_name

string

Yes

The customer's first name

last_name

string

Yes

The customer's last name

loyalty_card_number

string

Yes

The customer's loyalty card number value

order

array

OrderRequestBody

No

An order object, formatted by our system, containing information about the customer's current order

phone_number

string

Yes

The customer's phone number

zip_code

string

Yes

The customer's zip code

acquired_method

string (enum)

Yes

Represents the method used to acquire customer's loyalty identifier. The possible values are as follows:

general

GeneralRequestBody

Yes

Includes the fields for the GeneralRequestBody

check_id

string

Yes

The POS check identification

order

array

OrderRequestBody

Yes

The object with the order details

receipt_datetime

string

Yes

The order's receipt date time

general

GeneralRequestBody

Yes

Includes the fields for the GeneralRequestBody

check_id

string

Yes

The POS check identification

order

array

OrderRequestBody

Yes

The list of all items included in the order

receipt_datetime

string

Yes

The order's receipt date time

general

GeneralRequestBody

Yes

Includes the fields for the GeneralRequestBody

check_id

string

Yes

The POS check identification

order

array

OrderRequestBody

Yes

The list of all items included in the order

receipt_datetime

string

Yes

The order's receipt date time

general

GeneralRequestBody

Yes

Includes the fields for the GeneralRequestBody

check_id

string

Yes

The POS check identification

order

array

OrderRequestBody

Yes

The object containing all order details

general

GeneralRequestBody

Yes

Includes the fields for the GeneralRequestBody

merchant_data

object

Yes

The provider information

merchant_data.response_code

string

Yes

The response HTTP code

merchant_data.response_message

string

Yes

The response message from the provider or client

merchant_data.response_name

string

Yes

The response name

merchant_data.authorization_code

string

Yes

The request authorization code

merchant_data.id

string

Yes

The provider identification

merchant_data.name

string

Yes

The provider name

host_txn_id

string

Yes

The transaction identification value

server_date_time

string

Yes

The response date and time

rewards_data.declined_rewards[].amount

number

Yes

The declined reward amount value.

rewards_data.declined_rewards[].name

string

Yes

The declined reward name

rewards_data.declined_rewards[].reward_id

string

Yes

The declined reward identifier

rewards_data.declined_rewards[].offer_id

string

Yes

The identifier of the matching offer

rewards_data.declined_rewards[].program_id

string

No

The declined reward's program identification

rewards_data.declined_rewards[].calculated_by

string

Yes

Indicates the party responsible for the loyalty rewards.

This should be set to "provider" when the loyalty rewards are calculated and validated by a loyalty provider.

This should be set to "client" when the loyalty rewards are calculated and validated by us.

rewards_data.declined_rewards[].error

object

Yes

The declined reward error details

rewards_data.declined_rewards[].error.error_code

string

Yes

The error HTTP code

rewards_data.declined_rewards[].error.error_message

string

Yes

The error message

rewards_data.redeemed_rewards[].reward_id

string

Yes

The reward identifier

rewards_data.redeemed_rewards[].name

string

Yes

The reward name

rewards_data.redeemed_rewards[].quantity_redeemed

number

Yes

The reward quantity

rewards_data.redeemed_rewards[].amount

number

Yes

The reward discount amount

rewards_data.redeemed_rewards[].apply_automatically

boolean

Yes

The flag that identifies if the reward should be applied automatically.

rewards_data.redeemed_rewards[].redemption_code

string

No

The reward redemption identifier

rewards_data.redeemed_rewards[].program_id

string

No

The reward's program identifier

rewards_data.redeemed_rewards[].rewarded_items

list {object}

No

Available for the item-level discounts only, and contains the list of items to which the discount should be applied

rewards_data.redeemed_rewards[].rewarded_items.name

string

Yes

The item name

rewards_data.redeemed_rewards[].rewarded_items.quantity

number

Yes

The item quantity

rewards_data.redeemed_rewards[].rewarded_items.amount

number

Yes

The item amount

rewards_data.redeemed_rewards[].rewarded_items.id

string

Yes

The item identifier

rewards_data.redeemed_rewards[].rewarded_items.item_id

string

No

The unique item identifier in the order. The identifier should match the order_item_id value of the item in the request.

rewards_data.redeemed_rewards[].transaction_id

string

No

The redemption transaction identifier, if the rewards were redeemed one by one

receipt.balance

list {object}

No

The list of customer's loyalty balances that should be printed on a receipt. For example, points or visits.

receipt.balance[].balance

string

No

The customer's loyalty balance

receipt.balance[].name

string

No

The loyalty balance's name. For example, Points.

receipt.balance[].type

string

No

The loyalty balance type

receipt.balance[].points_redeemed

string

No

The amount of points redeemed in the current transaction

receipt.balance[].points_earned

string

No

The amount of points earned in the current transaction

receipt.balance[].expiration_dates

list {object}

No

The loyalty balance expiration dates

customers.balance[].expiration_dates[].expiration_date

string

No

The loyalty balance expiration date

receipt.balance[].expiration_dates[].points_quantity

string

No

The balance amount to be expired

receipt.customer_name

string

No

The loyalty customer's name

receipt.loyalty_card_number

string

No

The customer's loyalty card number

receipt.messages

array

No

The receipt messages

receipt.loyalty_messages

list {object}

No

The receipt loyalty footer and header messages

receipt.loyalty_messages[].type

string (enum)

No

The type of the message. The possible values are as follows:

receipt.loyalty_messages[].text

string

No

The text of the message

receipt.loyalty_id

string

No

The loyalty account identifier

receipt.receipt_code

string

No

The loyalty receipt code

receipt.rewards

list {object}

No

The list of loyalty rewards available on the customer's balance

receipt.rewards[].id

string

No

The reward identification value

receipt.rewards[].name

string

No

The reward name

receipt.rewards[].balance

string

No

The reward quantity

receipt.rewards[].status

string

No

The reward status

receipt.rewards[].associated_points

string

No

The amount of points associated with the reward

receipt.rewards[].expiration_dates

list {object}

No

The reward expiration dates

receipt.rewards[].expiration_dates[].expiration_date

string

No

The reward expiration date

receipt.rewards[].expiration_dates[].points_quantity

string

No

The total number of rewards to expire

customers.balance[].balance

string

No

The customer's loyalty balance

customers.balance[].name

string

No

The loyalty balance's name. For example, Points.

customers.balance[].type

string

No

The loyalty balance type

customers.balance[].expiration_dates

list {object}

No

The loyalty balance expiration dates

customers.balance[].expiration_dates[].expiration_date

string

No

The loyalty balance expiration date

customers.balance[].expiration_dates[].points_quantity

string

No

The balance amount to be expired

customers.cards[].card_number

string

No

The customer's stored value account or card number

customers.cards[].card_balance

string

No

The customer's stored value account or card balance

customers.information.id

string

No

The customer identification value

customers.information.loyalty_card_number

string

No

The customer's loyalty card or account number

customers.information.first_name

string

No

The customer's first name

customers.information.last_name

string

No

The customer's last name

customers.information.email

string

No

The customer's email

customers.information.phone

string

No

The customer's phone number

customers.information.birth_date

string

No

The customer's birth date

customers.information.address

string

No

The customer's address information

customers.information.address.address_1

string

No

The customer's main address

customers.information.address.address_2

string

No

The customer's additional address information

customers.information.address.address_3

string

No

The customer's additional address information

customers.information.address.city

string

No

The customer's city location

customers.information.address.instructions

string

No

The customer's address instructions

customers.information.address.state

string

No

The customer's state location

customers.information.address.zip_code

string

No

The customer's zip code location

customers.information.preferred_tips

list {object}

No

The list of customer's preselected tips

customers.information.preferred_tips[].calc_method

string (enum)

No

The customer's preselected tips calculation method. The possible values are as follows:

customers.information.preferred_tips[].order_amount

string

No

The order total amount threshold

customers.information.preferred_tips[].value

string

No

The tip amount to be added to the order