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:

OperationPurpose
GET /v1/loyalty/membersFind out whether an email belongs to a program member.
POST /v1/loyalty/creditsCredit an order on the member's card.

Before you start

  1. 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.
  2. An API key with the loyalty:credit scope, 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.
  3. 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"
  }'
FieldPurpose
establishmentIdLocation where the order is placed. It determines the program, even when the program covers several locations.
emailThe buyer's email, the one used to join the program.
amountCentsOrder amount including tax, in cents, a positive integer.
orderReferenceUnique and stable order reference, 1 to 128 characters. It prevents any double credit.
orderedAtOrder 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

ResponseCauseWhat to do
400 invalid_requestMissing or invalid field, or orderedAt in the futureFix the request.
403 insufficient_scopeThe key does not carry loyalty:creditCreate a key with this scope.
403 tenant_read_onlyThe account is read-onlyRestore the subscription.
404 not_foundUnknown location, or one from another accountCheck establishmentId.
404 member_not_foundThe buyer is not a confirmed member of the programDo not retry. Suggest that they sign up.
409 loyalty_program_pausedThe program is pausedDo not retry.
409 loyalty_program_not_activeThe program is a draft or has endedDo not retry.
409 daily_credit_limit_reachedThe card was already credited as often as allowed todayDo not retry.
422 unprocessableInvalid amountSend a positive integer amount, in cents.
429 rate_limitedMore than 120 calls per minute with the keyWait for Retry-After, then resend the same order.

The errors guide describes the shared format of these responses.

Updated on November 18, 2026