Loyalty Program

General

SCAYLE supports various loyalty-related features like attaching loyalty card numbers, verifying them, registering for loyalty programs, earning and paying with loyalty points. A custom adapter connects SCAYLE's API to specific loyalty systems.

When a customer submits a loyalty card number, a validation request is sent to your configured web service.

Configuration

Enable Loyalty Program

The loyaltyProgramneeds to be enabled in config.json on the Shops > [Shop] > Storefront > Checkout Settings page.

Enable loyalty in config.json

javascript

Copy

...
    "loyaltyProgram": {
      "enabled": true,
      "disableRemoval": false,
      "minLength": 10,
      "maxLength": 16,
      "type": "payback",
      "icon": {
        "enabled": true
      },
      "toolTip": {
        "enabled": true
      },
      "redeemablePoints": {
        "enabled": true
      },
      "registration": {
        "enabled": true,
        "disableForGuest": false
      }
...

Configure Loyalty Programs in the SCAYLE Panel

1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > Loyalty Programs.

Configure the URL and token to your webservice in the SCAYLE Panel:

Add New Loyalty Program

To add a new loyalty program in the SCAYLE Panel:

1. Go to Shops > [Shop] > Storefront > Checkout Settings.
2. Click + Loyalty Programs.
3. Enter the Name of loyalty program to identify for configuration (this has no technical significance).
4. Enter a Key identifier of the loyalty program. This will be sent along with the request payloads of the loyalty API requests, such as validation of the card number or registration.
5. Select Is enabled if the program is to be active on the front end. Select Is auto apply if it is automatically selected (otherwise the customer has to select it).
6. Enter the Calculation factor for the points assignment. For example, 0.1 means the customer gets 10 points for a €100 purchase.
7. Enter the Rounding applied to the earnable points. Only whole numbers are supported for point calculation.
8. Select Registration to connect an endpoint and token.
9. Select Validation method, Conversion rate, Balance, Capture, and Refund for the submitted loyalty number using your own API endpoints or an external webservice (e.g., luhn).
10. Click Save.

Loyalty widget

Once configured, you will see a new widget in your checkout frontend:

Once a valid loyalty card number is submitted, SCAYLE will attach this number to the customer and also to the order. In case the customer comes back to the checkout later, the loyalty card number will still be attached. Orders, which are confirmed with an attached loyalty card number, will carry this number in their payload when fetching them via APIs or web hooks. This information will be included in the object loyaltyCard.

Earnable points

Earnable points are calculated based on the order total after subtracting any:

• voucher reduction
• loyalty point reduction
• gift card reduction

but before any fees like shipping costs are applied.

Example

Assuming the calculation factor is 3, the following table would describe the outcome considering different scenarios, starting with an order total of 59.95€ without any reduction and adding up different reductions.

Verify the loyalty card number

For customers who have received their loyalty card via different channels, it is necessary to verify the submitted loyalty card.

In the SCAYLE Panel:

1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > Loyalty Program.
2. In the Key field, enter the type configured in the Enable Loyalty Program.
3. Select Auto-apply loyalty program.
4. Under validation method, choose the option API.
5. Add the full URL to your webservice and the access token.

Allow customers to pay with loyalty points

You can enable your customers to use their loyalty points within Checkout to reduce the order total. This feature is based on the configuration and integration of four endpoints: Conversion rate, Balance, Capture, Refund.

Configure all required endpoints

To enable this feature, it is mandatory to configure all four endpoints in the SCAYLE Panel:

1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > Loyalty Program.
2. Set the method to API and tokens for all four endpoints:
   1. Conversion rate: https://yourwebservice.com/conversion
   2. Balance: https://yourwebservice.com/balance
   3. Capture: https://yourwebservice.com/capture
   4. Refund: https://yourwebservice.com/refund

Example json configuration

json

Copy

"features": {
  "loyaltyProgram": {
    "enabled": true,
    "minLength": 10,
    "maxLength": 16,
    "type": "your_loyalty_program",
    "icon": { "enabled": true },
    "registration": {
      "enabled": true,
      "disableForGuest": false
    },
    "redeemablePoints": {
      "enabled": true
    },
  }
}

Detailed endpoint information

Conversion rate

The conversion rate endpoint will be requested by SCAYLE every x minutes per configured loyalty program and currency. The response has to contain the conversion factor, which is applied to convert the point balance to a reduction in a specific currency like EUR or GBP.

Example:

Copy

GET /loyalty/points-rate?currency=EUR&type=your_loyalty_program

This also means that the conversion rate can be different for every currency and loyalty program combination.

Balance

The balance endpoint will be requested by SCAYLE every minute for customers that are in the checkout frontend and have a loyalty card number attached. The balance will be cached for one minute on the SCAYLE side.

An exemplary request could look like this:

GET /loyalty/balance?cardKey=abc123&type=your_loyalty_program

In the response, you need to return the current loyalty balance of the provided card number, for instance:

{ "balance": 2500 }

The returned balance will impact the state of the frontend widget.

Capture

A capture request will be queued up and retried up to two days for every confirmed order, that was at least partially paid with loyalty points.

In order for the capturing to work as expected the MembershipOperationManager needs to be enabled. Please contact your SCAYLE Key Account Manager for more information.

Example request:

json

Copy

{
    "amount": 10000, 
    "cardKey": "abc123",
    "type": "your_loyalty_program",
    "currencyCode": "EUR",
    "orderId": 2345234,
    "transactionKey": "68ff99b453c1d302c26b46b68ffc"
}

Refund

This endpoint is called by SCAYLE in two cases:

1. The virtual stock handling of SCAYLE determines that items are not available.
2. The order delegation failed finally after two days. In this case, also a refund is triggered

SCAYLE is currently not supporting the refund of loyalty points based on return or cancellation information provided via https://new.scayle.dev/en/developer-guide/logistics/shipments-and-returns#create-a-cancellation and https://new.scayle.dev/en/developer-guide/logistics/shipments-and-returns#create-a-return-request

Example request:

json

Copy

{ "amount": 10000, "cardKey": "abc123", "type": "so_loyalty" "currencyCode": "EUR", "orderId": 2345234, "transactionKey": "8ff99b453c1d302c26b46b68ffc6" }

Best practices

• Only customers, who verified their loyalty card number at Checkout, can collect points: so make sure to have a working loyalty verification handling in place, refer to the Verify the loyalty card number
• Use the order-confirmed webhook to be informed about orders. The included object loyaltyCard can tell you, how many points were earned. If this object is missing, the customer did not attach a loyalty card number to his order
• Ensure idempotency in your system, as an only-once-delivery cannot be guaranteed, to avoid duplicate booking of points
• In case you are not planning to enable customers to earn points, you could just remove the variable representing the earned points from the translation