Loyalty Integration Guide

This guide covers the expected flow, responsibilities, and system interactions. For the full API reference and Panel configuration, see Setting up Loyalty Programs.

Introduction

Loyalty features in the checkout process are essential for customer retention. By rewarding repeat purchases, they make the experience more personal and enhance customer satisfaction, encouraging long-term loyalty.

SCAYLE supports several loyalty-related features within the checkout, allowing customers to:

• Register for the loyalty program.
• Attach an existing loyalty card number to their profile.
• Earn loyalty points on their purchases.
• Pay for orders using loyalty points.

These features are designed to work with external loyalty systems. The SCAYLE Checkout sends generic API requests to a custom loyalty adapter, which then connects to your specific loyalty provider.

This guide walks you through integrating an external loyalty system with the SCAYLE Checkout, outlining the required API endpoints, SCAYLE Panel configurations, and the resulting customer experience.

Reference Architecture

SCAYLE's loyalty features are designed to work with various external loyalty systems. However, the SCAYLE Checkout does not support direct, native integration with specific loyalty providers. For this reason, a custom adapter, often referred to as loyalty middleware, is required. This adapter receives generic requests from the SCAYLE Checkout and translates them into the specific format required by your loyalty provider. For the full endpoint specification, see Setting up Loyalty Programs.

Specification of Endpoints

Endpoint Naming

The specific URL paths for your endpoints are entirely flexible. You configure the full URL for each implemented endpoint in the SCAYLE Panel. For setup details, see Configure Endpoints in the SCAYLE Panel.

Authentication

Every request sent by the SCAYLE Checkout includes an Authorization header, which you configure in the SCAYLE Panel. For setup details, see Configure Endpoints in the SCAYLE Panel. To ensure the security of user data, properly manage and rotate Bearer tokens.

Validation Endpoint

This endpoint is triggered by customer actions during the checkout process. Its primary purpose is to verify the validity of a submitted loyalty card against your external service. The response must indicate whether the card is valid and must return the customer's current loyalty point balance.

Conversion Rate Endpoint

The purpose of this endpoint is to provide SCAYLE with the conversion factor used to transform a customer's loyalty point balance into a monetary value for a specific currency.

Because SCAYLE does not support the configuration of a static default value for the conversion rate in the SCAYLE Panel, implementing this endpoint is a prerequisite for enabling point redemption logic.

Book Points Endpoint

This endpoint is called by SCAYLE after an order is successfully confirmed to communicate the number of loyalty points the customer has earned. Implementing this endpoint is mandatory.

Your loyalty middleware is responsible for crediting the points to the customer's balance in the external loyalty system. To prevent duplicate credits in the event of retried requests, the operation must be idempotent — use the orderKey as a unique reference.

Check Balance Endpoint

This endpoint is called during checkout immediately after the customer's loyalty card number has been successfully validated. SCAYLE uses the returned balance to determine whether the customer is eligible to redeem points and, if so, to calculate the redeemable amount for display in the checkout widget.

The customer's email is an optional parameter provided by SCAYLE. You can use it to support personalized experiences or any required internal processes.

Capture Endpoint

A capture request is sent for every confirmed order that is at least partially paid for with loyalty points. These requests are queued and automatically retried to ensure the points are successfully deducted from the external loyalty system.

If a capture operation fails, SCAYLE retries the request every 60 minutes for up to 100 attempts (approximately 4 days). If all retry attempts fail, the order is automatically cancelled.

Refund Endpoint

This endpoint is triggered by SCAYLE to refund loyalty points when a confirmed order fails before it has been successfully delegated. This typically occurs when all order delegation attempts fail, requiring a full refund of all captured loyalty points for the entire order.

This endpoint is not called for standard post-delegation events, such as customer-initiated returns or cancellations after an order has been processed. Your system is responsible for managing loyalty logic in these cases:

• Revoking earned points: If a customer returns an item, any points earned from that purchase must be deducted from their balance.
• Refunding spent points: If a customer cancels or returns an order paid for with points, those points must be manually credited back to their balance via your internal logic.

Verify Endpoint

This endpoint is optional and should be implemented only if your loyalty program requires strict customer identification — for example, matching the submitted card number against the customer's registered email address.

If implemented, SCAYLE Checkout calls this endpoint immediately after the card validation step. A successful response confirms that the customer is eligible to earn and redeem loyalty points for the current session.

Registration Endpoint

This endpoint is called when a customer signs up for the loyalty program directly within the checkout process. Implementing this feature is optional. While SCAYLE sends the relevant customer data to this endpoint, your loyalty middleware must handle all registration logic within the external system. A successful response must return the newly generated loyalty card number, which SCAYLE then associates with the customer's profile.

Alternatively, you can assign a loyalty card to a customer in advance via the SCAYLE Admin API with the POST /shops/{shopKey}/countries/{countryCode}/customers/{customerIdentifier}/memberships endpoint (see Create a new customer membership). If a membership is created this way, the customer is already recognized as a loyalty member and does not need to register manually during the checkout process.

Dynamic Points Calculation Endpoint

This endpoint is called by SCAYLE instead of applying the static Calculation Factor when Dynamic Points Calculation is enabled for the loyalty program. It receives the full confirmed order data and is expected to return the exact number of points the customer should earn, allowing you to apply any custom business logic — such as promotion-based bonuses, customer segment rules, or product-level exclusions — without being constrained by a fixed factor.

If this endpoint is configured, the Conversion Rate endpoint is not required.

Customer Actions and System Interactions in Checkout

This section describes how customer interactions within the Checkout trigger communication between SCAYLE and your loyalty middleware.

Attach a Loyalty Card to a Customer's Account

There are three ways a loyalty card can be linked to a customer's account.

1. Automated attachment via Admin API

Loyalty cards can be attached to profiles programmatically. A common use case is automatically enrolling customers upon account registration. In this scenario, your service would:

• Listen for customer-created webhooks from SCAYLE.
• Generate a new loyalty card in your loyalty system.
• Use the SCAYLE Admin API endpoint POST /shops/{shopKey}/countries/{countryCode}/customers/{customerIdentifier}/memberships to attach the card to the customer profile. For details, see Create a new customer membership.

2. Manual attachment of an existing card

Customers can manually enter an existing loyalty card number during the checkout process. This is ideal for users with physical cards. When a number is submitted:

• SCAYLE sends a request to the Validation endpoint.
• If the service confirms the card is valid, it is attached to both the customer's profile and the current order.

3. Manual registration at Checkout

Customers without a card can sign up directly in the Checkout widget.

• When the form is submitted, SCAYLE calls your Registration endpoint.
• Your service handles the account creation and returns the new card number.
• SCAYLE then applies this number to the checkout session and the customer profile.

If you use automated association (Option 1), you may want to disable the registration widget in the Checkout to avoid confusion. You can manage this in the SCAYLE Panel under Settings ➜ Checkout ➜ Customization ➜ Payment Step ➜ Loyalty Program, where you can define:

• Whether manual registration is enabled.
• Whether guest customers are allowed to register.

Customer Earns Loyalty Points

For customers with a valid loyalty card attached, the Checkout displays the estimated points they earn for their purchase. This amount is automatically recalculated whenever the basket changes (for example, adjusting item quantities or applying a discount code).

How Earnable Points Are Calculated

The calculation logic is defined in the Loyalty Programs section of the SCAYLE Panel. The Calculation Factor is applied to the order total to determine the number of points.

The calculation is based on the order total after any promotions, vouchers, gift cards, or loyalty point reductions are applied, but before shipping costs are added. A rounding rule (up or down) is applied to the final amount, as only whole numbers are supported for earnable points.

Products can be excluded from the loyalty program. For more information, see Exclude Products from the Loyalty Program.

System Interaction and Responsibilities

While SCAYLE calculates the points, your external loyalty service is responsible for managing the customer's total balance. SCAYLE facilitates this by providing the points data once an order is finalized.

1. After an order is successfully placed, SCAYLE includes the earned points in the order data (Order Delegation payload, webhooks, and Admin API get-order payload). This information is transmitted within the loyaltyCard object:

json

Copy

2. Your loyalty service must extract the points value and credit it to the customer's balance. The operation must be idempotent to prevent duplicate credits for the same order. Use the SCAYLE order_id or the reference_key as a reference to prevent crediting points multiple times for the same transaction in the event of retried webhooks.

The amount of earned loyalty points on an order is displayed on the order's detail page in the SCAYLE Panel.

Customer Pays with Loyalty Points

You can enable customers to use their accumulated points as a payment method to reduce their order total. This process involves a series of interactions between the SCAYLE Checkout and your loyalty middleware.

Products can be excluded from the loyalty program. For more information, see Exclude Products from the Loyalty Program.

How Redeemable Points Are Calculated

To display the redeemable amount, SCAYLE performs the following:

1. Calls the Validation endpoint to fetch the current point balance.
2. Calls your Conversion Rate endpoint to retrieve the factor for converting points into the local currency.
3. The Checkout widget displays the balance and its monetary equivalent.

Order Processing

Once an order is placed, the following sequence occurs:

• If applicable, the primary payment method (for example, credit card) is authorized or captured first.
• If applicable, the voucher and promotion usage count increases.
• Once the primary payment is successful, SCAYLE sends a request to your Capture endpoint.

The burned points data is included in the membershipDiscount object:

json

Copy

• membershipCardId integer – The SCAYLE internal identifier of the loyalty card number.
• pointsUsed integer – The number of points that were redeemed.
• reductionValue integer – The corresponding reduction value (in cents) in the specific currency.
• tax integer – The tax associated with this reduction.

If a Capture request fails, the checkout retries every 60 minutes for 100 attempts. If all retries also fail, the order is cancelled, and SCAYLE triggers a refund of the payment with the regular payment method.

Handling Insufficient Balances

If a customer attempts to spend more points than they have (for example, through simultaneous orders), you can handle the Capture request in one of two ways:

1. Do not modify the balance and respond with the status code 406. SCAYLE retries the capture request. If unsuccessful, the order is cancelled, and the primary payment is refunded.
2. Deduct the points even if it results in a negative balance and respond with the status code 200. The order is confirmed and delegated immediately.

Exclude Products from the Loyalty Program

To maintain flexibility in your business strategy, you can exclude specific products, such as gift cards, from participating in the loyalty program. When a product is excluded, customers neither earn points on its purchase price nor are able to apply loyalty points to pay for that specific item.

Customer Experience

The Checkout frontend dynamically adjusts based on the contents of the customer's basket:

• If the basket contains only excluded products, the loyalty component (widgets for registration or point redemption) is not displayed at all.
• If the basket contains both eligible and excluded products, the loyalty component remains visible. However, the system excludes the value of the restricted items when calculating the estimated earnable points and the maximum points available for redemption. For mixed baskets, the reductionValue and earnedPoints calculations only reflect the eligible portions of the order total.

Post-Purchase: Enriching Customer Communication

Adding Loyalty Data to Transactional Emails

You can enhance your transactional emails (such as order confirmations) by including details about the loyalty points a customer earned or redeemed. When a loyalty card is associated with an order, all relevant information is accessible in your email templates via the data.order.membershipDiscount object.

The following JSON snippet illustrates the data structure available for your templates:

json

Copy

• cardNumber string – Unique customer's loyalty identifier.
• earnedPoints integer – The number of points the customer earned from this order.
• membershipCardId integer – The SCAYLE internal identifier of the loyalty card number.
• pointsUsed integer – The number of points that were redeemed.
• reductionValue integer – The corresponding reduction value (in cents) in the specific currency.
• tax integer – The tax associated with this reduction.