Credit an online order on the loyalty card
Let customers who order on your website earn points based on the order amount, with nothing for your team to do: member lookup, credit, safe retries and errors.
API documentationGuides · Online orders and loyalty
What the integration does
Your online ordering website or your till sends each confirmed order to Ma Belle Note. The buyer's loyalty card is credited based on the amount, exactly like a credit made at the counter by the team: same spend tiers, same limits, same rewards. The team has nothing to do. It hands over the reward on site, with the usual screen, when the customer picks up the order.
Two operations, in beta:
| Operation | Purpose |
|---|---|
GET /v1/loyalty/members | Find out whether an email belongs to a program member. |
POST /v1/loyalty/credits | Credit an order on the member's card. |
Before you start
- An active loyalty program on the location. In "Based on the amount spent" mode, points follow the program's spend tiers. In "On every visit" mode, each order earns the program's default points.
- An API key with the
loyalty:creditscope, shown in the app as "Credit loyalty cards". Keys are created in Settings › Integration, API & webhooks. The API is included in the Pro plan and in the free trial. - Calls from your server, never from the browser: customers must not be able to see the key.
How the customer becomes a member
Customers join the program themselves, through the program's signup address or QR code, and confirm their email. Make this address visible on your website, for instance on the order confirmation page. Only confirmed members are credited, and customers must order with the email they signed up with. An order placed before signing up is not credited afterwards.
Write the program rules in the app (Loyalty, your program, Edit, "Program rules" field): they are shown on the signup page. For example: "Online orders placed with the email you signed up with are credited automatically. Orders placed before you signed up are not." Ma Belle Note adds no wording of its own.
1. Check that the buyer is a member (optional)
To show "You will earn points" or "Sign up to earn points" at checkout:
curl -G https://api.mabellenote.com/v1/loyalty/members \
-H "Authorization: Bearer $MBN_API_KEY" \
--data-urlencode "establishmentId=kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p" \
--data-urlencode "[email protected]"
{
"object": "loyalty_member",
"id": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
"establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
"programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
"contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
"contactExternalId": null,
"balance": 12,
"nextReward": { "label": "A free dessert", "pointsRequired": 15, "pointsRemaining": 3 },
"joinedAt": "2026-11-02T18:40:00.000Z"
}
An unknown email, a signup not yet confirmed or a member of another program all answer 404 member_not_found.
2. Credit the confirmed order
Call the operation as soon as the order is confirmed, with the amount including tax in cents and the order reference in your system:
curl https://api.mabellenote.com/v1/loyalty/credits \
-H "Authorization: Bearer $MBN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
"email": "[email protected]",
"amountCents": 3450,
"orderReference": "CMD-2026-11-17-0042",
"orderedAt": "2026-11-17T11:30:00.000Z"
}'
| Field | Purpose |
|---|---|
establishmentId | Location where the order is placed. It determines the program, even when the program covers several locations. |
email | The buyer's email, the one used to join the program. |
amountCents | Order amount including tax, in cents, a positive integer. |
orderReference | Unique and stable order reference, 1 to 128 characters. It prevents any double credit. |
orderedAt | Order date, optional, kept for information. It cannot be in the future. |
With the tiers €1: 1 point, €10: 3 points, €30: 5 points, an order of €34.50 earns 5 points:
{
"object": "loyalty_order_credit",
"alreadyRecorded": false,
"credit": {
"object": "loyalty_points_credit",
"id": "mv2c5f8i1l4o7r0u3x6a9d2g5j8m1p4s",
"memberId": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
"establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
"programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
"contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
"contactExternalId": null,
"points": 5,
"amountCents": 3450,
"orderReference": "CMD-2026-11-17-0042",
"source": "api",
"balance": 17,
"creditedAt": "2026-11-17T11:32:08.000Z"
},
"rewards": [
{
"object": "loyalty_reward",
"id": "gn8k1n4q7t0w3z6c9f2i5l8o1r4u7x0a",
"memberId": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
"establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
"programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
"contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
"contactExternalId": null,
"tierRank": 2,
"label": "A free dessert",
"issuedAt": "2026-11-17T11:32:08.000Z",
"usableFrom": "2026-11-17T11:32:08.000Z",
"expiresAt": "2026-12-17T11:32:08.000Z"
}
]
}
rewards lists the rewards unlocked by this credit: you can tell the customer that a reward is waiting at pickup. The credit updates the card, including in the customer's Wallet, and produces the loyalty_points.credited event, with origin api, and loyalty_reward.issued, delivered to your webhooks. In the app, the card history shows the credit with the "via API" badge, the order number and the key name.
The same rules as at the counter
- One visit of the day: each credit counts as a visit, and the program's daily visit limit is shared with the counter. Beyond it, the API answers
409 daily_credit_limit_reached. - Amount below the first tier: the visit is counted, with 0 points.
- Credit date: the credit is dated when it is received. An order sent again the next day counts for the next day.
- Large amount: above €500, the app asks the team to confirm. Through the API, since the amount comes from your ordering system, it is accepted without confirmation.
- Cancelled order: nothing is cancelled through the API. The business corrects the balance in the app, with a reason.
Retry safely
An order is credited only once per member, however many times it is sent. If the same orderReference comes back, nothing is credited again: the response is 200 instead of 201, with alreadyRecorded: true and the original credit. You can therefore resend an order after a network failure or a 5xx response without any risk of a duplicate. The Idempotency-Key header is accepted but not needed: the order reference plays that role.
Never make the order depend on this call. If Ma Belle Note does not answer, confirm the order, then send the credit again later from a queue.
Server-side example
const API = "https://api.mabellenote.com/v1";
export async function creditOnlineOrder(order) {
const response = await fetch(`${API}/loyalty/credits`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MBN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
establishmentId: order.establishmentId,
email: order.customerEmail,
amountCents: order.totalCents,
orderReference: order.reference,
orderedAt: order.validatedAt,
}),
});
if (response.ok) {
const result = await response.json();
return { status: "credited", points: result.credit.points, rewards: result.rewards };
}
const problem = await response.json();
switch (problem.code) {
case "member_not_found":
return { status: "not_a_member" };
case "daily_credit_limit_reached":
case "loyalty_program_paused":
case "loyalty_program_not_active":
return { status: "not_credited", reason: problem.code };
case "rate_limited":
return { status: "retry", afterSeconds: Number(response.headers.get("Retry-After")) };
default:
if (response.status >= 500) return { status: "retry", afterSeconds: 60 };
throw new Error(`Loyalty credit failed: ${problem.code} (${problem.requestId})`);
}
}
not_a_member and not_credited are normal outcomes: record them without retrying. Only retry and configuration errors call for action.
Errors to handle
| Response | Cause | What to do |
|---|---|---|
400 invalid_request | Missing or invalid field, or orderedAt in the future | Fix the request. |
403 insufficient_scope | The key does not carry loyalty:credit | Create a key with this scope. |
403 tenant_read_only | The account is read-only | Restore the subscription. |
404 not_found | Unknown location, or one from another account | Check establishmentId. |
404 member_not_found | The buyer is not a confirmed member of the program | Do not retry. Suggest that they sign up. |
409 loyalty_program_paused | The program is paused | Do not retry. |
409 loyalty_program_not_active | The program is a draft or has ended | Do not retry. |
409 daily_credit_limit_reached | The card was already credited as often as allowed today | Do not retry. |
422 unprocessable | Invalid amount | Send a positive integer amount, in cents. |
429 rate_limited | More than 120 calls per minute with the key | Wait for Retry-After, then resend the same order. |
The errors guide describes the shared format of these responses.
Updated on November 18, 2026

