Basic Usage
Awarding points, looking up cards, coupons and games in Python
Basic Usage
Award points for a purchase
One call registers the order and credits the points. Identify the customer by
user_email or user_id; order_id is your own reference and is required.
transaction = sdk.create_transaction(
user_email='customer@example.com',
order_id='ORD-2024-001',
order_total=25.50,
currency='EUR',
shop_id=1,
description='Online purchase',
)Points come from order_total and the partner's rules. Pass points to set the
amount yourself, and report any points the customer spent on the same order:
sdk.create_transaction(
user_email='customer@example.com',
order_id='ORD-2024-003',
order_total=45.00,
points_redeemed=500,
points_discount_amount=5.00,
)Reverse a transaction
Same order_id, with transaction_type set to cancellation or refund. The SDK
names the argument transaction_type because type is a Python builtin; it is sent to
the API as type, the same field the other SDKs use.
sdk.create_transaction(
user_email='customer@example.com',
order_id='ORD-2024-001',
transaction_type='refund',
order_total=25.50,
)History
history = sdk.get_transactions(page=1, per_page=20)Loyalty cards
card = sdk.get_loyalty_card_info(user_id=user_id)
balance = sdk.get_points_balance(card_id=card['id'])
designs = sdk.get_loyalty_cards(per_page=50) # card designs, not customersget_loyalty_card_info accepts card_id, card_number, user_id or user_email.
Coupons
check = sdk.verify_coupon('SUMMER10', shop_id)
discount = sdk.calculate_coupon_discount('SUMMER10', 50.00)
sdk.set_coupon_pending(check['coupon']['id'], shop_id) # hold during checkout
sdk.redeem_coupon(check['coupon']['id'], shop_id) # final
# or, if the sale falls through:
sdk.cancel_pending_coupon(check['coupon']['id'], shop_id)
coupons = sdk.get_card_coupons(shop_id, card_id=card_id)Games and stamp cards
games = sdk.list_games(shop_id)
active = sdk.get_card_games(card_id, shop_id)
sdk.add_stamps(game_id, card_id, shop_id, stamps_count=1)
progress = sdk.get_game_progress(game_id, card_id)A full stamp card issues its reward automatically. complete_game() and
restart_game() close and restart a round by hand.
Shops and offers
shops = sdk.get_shops() # shop_id values for the calls above
offers = sdk.get_offers()Errors
from loyalty_sdk.exceptions import LoyaltySDKError
try:
sdk.create_transaction(order_id='ORD-1', user_email='nobody@example.com')
except LoyaltySDKError as e:
if e.http_status == 422:
logger.warning('Invalid request: %s', e.message)
elif e.http_status == 401:
logger.error('Check your API credentials')
else:
logger.error('%s: %s', e.code, e.message)http_status is the HTTP status; code is the API's numeric application code.
429 and 5xx are retried automatically.
Django example
def award_points(order):
try:
sdk.create_transaction(
user_email=order.customer_email,
order_id=str(order.id),
order_total=float(order.total),
currency=order.currency,
shop_id=settings.LOYALTY_SHOP_ID,
)
except LoyaltySDKError:
logger.exception('Loyalty award failed for order %s', order.id)
# never block the order on a loyalty failureNext
QR login and QR card scan