Basic Usage
Awarding points, looking up cards, coupons and games in PHP
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->createTransaction([
'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->createTransaction([
'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 type set to cancellation or refund:
$sdk->createTransaction([
'user_email' => 'customer@example.com',
'order_id' => 'ORD-2024-001',
'type' => 'refund',
'order_total' => 25.50,
]);History
$history = $sdk->getTransactions(['page' => 1, 'per_page' => 20]);Loyalty cards
$card = $sdk->getLoyaltyCardInfo(['user_id' => $userId]);
$balance = $sdk->getPointsBalance(['card_id' => $card['id']]);
$designs = $sdk->getLoyaltyCards(['per_page' => 50]); // card designs, not customersgetLoyaltyCardInfo accepts card_id, card_number, user_id or user_email.
Coupons
$check = $sdk->verifyCoupon('SUMMER10', $shopId);
$discount = $sdk->calculateCouponDiscount('SUMMER10', 50.00);
$sdk->setCouponPending($check['coupon']['id'], $shopId); // hold during checkout
$sdk->redeemCoupon($check['coupon']['id'], $shopId); // final
// or, if the sale falls through:
$sdk->cancelPendingCoupon($check['coupon']['id'], $shopId);
$coupons = $sdk->getCardCoupons($shopId, $cardId);Games and stamp cards
$games = $sdk->listGames($shopId);
$active = $sdk->getCardGames($cardId, $shopId);
$sdk->addStamps($gameId, $cardId, $shopId, 1);
$progress = $sdk->getGameProgress($gameId, $cardId);A full stamp card issues its reward automatically. completeGame() and
restartGame() close and restart a round by hand.
Shops and offers
$shops = $sdk->getShops(); // shop_id values for the calls above
$offers = $sdk->getOffers();Errors
use LoyaltyLt\SDK\Exceptions\LoyaltySDKException;
try {
$sdk->createTransaction(['order_id' => 'ORD-1', 'user_email' => 'nobody@example.com']);
} catch (LoyaltySDKException $e) {
match ($e->getHttpStatus()) {
422 => logger()->warning('Invalid request: ' . $e->getMessage()),
401 => logger()->error('Check your API credentials'),
default => logger()->error($e->getErrorCode() . ': ' . $e->getMessage()),
};
}getHttpStatus() is the HTTP status; getErrorCode() is the API's numeric
application code. 429 and 5xx are retried automatically.
Laravel example
class LoyaltyService
{
public function __construct(private LoyaltySDK $loyalty) {}
public function awardForOrder(Order $order): void
{
try {
$this->loyalty->createTransaction([
'user_email' => $order->customer_email,
'order_id' => (string) $order->id,
'order_total' => $order->total,
'currency' => $order->currency,
'shop_id' => $order->shop_id,
]);
} catch (LoyaltySDKException $e) {
report($e); // never block the order on a loyalty failure
}
}
}Next
QR login and QR card scan