Custom API Integration: Sync Loyalty Information

If your loyalty program runs in another system, you can send each customer's balance and tier status to JeriCommerce so their loyalty card shows them. You do it with the same endpoint used for customer data, with loyalty as the feature. It accepts an array of up to 250 objects as the request body.

POST https://api.jericommerce.com/v1/programs/{program_slug}/integrations/api

This endpoint is part of the Custom API Integration. It needs the integration active under Settings > Integrations > API, with the Loyalty feature turned on. Otherwise it answers 403 with API_INTEGRATION_REQUIRED or API_LOYALTY_REQUIRED.

To add points to a JeriCommerce loyalty program instead of replacing the balance, use Increase balance.

It's important to know that the customer should exist before you can add loyalty information. If the customer doesn't exist, the loyalty item is skipped without an error.

You can add both the customer and loyalty information in the same API request, but you should ensure to preserve the order by adding the customer information first.

Here a body example to update a customer:

[
  {
    "email": "{{customer_email}}",
    "feature": "loyalty",
    "payload": {
      "loyaltyCustomerId": "{{customer_loyalty_id}}",
      "balance": "{{balance_to_apply}}",
      "memberSince": "{{customer_join_date}}",
      "tierStatus": "{{customer_tier}}"
    }
  }
]

Payload properties ¶

loyaltyCustomerId ¶

Is the external reference of this loyalty information, useful when you need to associate this information with another database. Is mandatory for each request. It is saved the first time and kept after that.

Balance ¶

One of the most important properties is the customer balance. Our API doesn't calculate any value here, but simply replaces the balance with the value provided in the request. It is a mandatory field. Send it as a number of 0 or more. Decimals are rounded to the nearest whole number.

memberSince ¶

Is the date when the customer was registered on your loyalty program, in ISO 8601 format (for example, 2026-01-31). It is optional. If you don't send it, JeriCommerce keeps the current date, or uses today's date for a new customer.

tierStatus ¶

Dependence on the loyalty program could have a tiered status or not, so you could add the name of the tier here. The optional string property could be the desired value.

Response ¶

The response follows the same rules as the customer endpoint: 201 when every item is saved. When the balance or tier changes, the customer gets a wallet notification if they have those notifications turned on.

The program's rewards catalog has its own endpoint: List rewards.