AlliDeskHelp centre

Loyalty API for checkouts

For a checkout that runs outside Shopify's own — GoKwik, Shiprocket, Razorpay Magic, Cashfree, Shopflo and others — to show a shopper their AlliDesk points and take them off the order.

  1. How it fits together

    The store makes an API key in AlliDesk under Settings → Integrations → API keys and sends it to you. At checkout you read the shopper's balance, redeem the points they choose (they are held and leave their balance), give the discount, then confirm the hold with the Shopify order ID once the order exists — or cancel it if the shopper changes their mind.

    POST https://app.allidesk.com/api/v1/loyalty/{balance | redeem | confirm | cancel}
Authorization: Bearer ald_live_…
Content-Type: application/json

  2. Rules

    • Call from your server only. The key spends a store's customers' points; it must never reach a browser or an app.
    • A hold that is neither confirmed nor cancelled within 2 hours goes back to the shopper. Confirm every order that used points.
    • Points leave the shopper's balance when you hold them, so a second tab cannot spend them twice.
    • Every answer is JSON. Errors look like { "error": { "code": "…", "message": "…" } }.

  3. POST /api/v1/loyalty/balance · Read a balance

    When the shopper reaches checkout and you know their phone or email.

    phoneThe shopper's phone. The last ten digits are matched.
    emailThe shopper's email. Send a phone, an email or both.
    cart_totalThe cart in rupees, before points. Used to work out how many points this order may take.
    Request
    {
  "phone": "+91 98765 43210",
  "cart_total": 1499
}
    Answer
    {
  "customer_found": true,
  "points": 1200,
  "points_value": 300,
  "redeemable_points": 599,
  "redeemable_value": 149.75,
  "rules": {
    "value_per_point": 0.25,
    "min_points": 100,
    "min_order": 499,
    "max_percent_of_order": 10
  },
  "currency": "INR"
}

  4. POST /api/v1/loyalty/redeem · Hold points for a checkout

    When the shopper chooses to use points. Take discount_amount off the order.

    phone / emailrequiredAs for balance.
    pointsrequiredWhole points to use. Must be no more than redeemable_points.
    cart_totalrequiredThe cart in rupees, before points.
    checkout_idrequiredYour own id for this checkout session. The same id and points again returns the same hold; different points replace it.
    sourceYour checkout's short name, shown to the store: gokwik, fastrr, razorpay…
    Request
    {
  "phone": "+91 98765 43210",
  "points": 400,
  "cart_total": 1499,
  "checkout_id": "chk_8841",
  "source": "gokwik"
}
    Answer
    {
  "redemption_id": "cmh2x0k7a0001",
  "checkout_id": "chk_8841",
  "points": 400,
  "discount_amount": 100,
  "status": "held",
  "order_id": null,
  "expires_at": "2026-09-17T14:05:00.000Z"
}

  5. POST /api/v1/loyalty/confirm · Confirm on the order

    As soon as the Shopify order is created with the discount on it.

    redemption_idrequiredFrom the redeem answer.
    order_idrequiredThe Shopify order ID, as a number or gid://shopify/Order/…. If that order is cancelled in Shopify, the points go back on their own.
    Request
    {
  "redemption_id": "cmh2x0k7a0001",
  "order_id": 5821930012345
}
    Answer
    {
  "redemption_id": "cmh2x0k7a0001",
  "points": 400,
  "discount_amount": 100,
  "status": "used",
  "order_id": "5821930012345"
}

  6. POST /api/v1/loyalty/cancel · Give the points back

    When the shopper removes points, changes their cart, or leaves without paying.

    redemption_idrequiredFrom the redeem answer.
    Request
    {
  "redemption_id": "cmh2x0k7a0001"
}
    Answer
    {
  "redemption_id": "cmh2x0k7a0001",
  "points": 400,
  "status": "cancelled",
  "points_returned": 400
}

  7. Errors

    400customer_required · invalid_points · invalid_amount · invalid_checkout_id · invalid_order_id
    A field is missing or not in the shape above.
    401unauthorized
    No key, a wrong key, or a revoked key.
    403forbidden
    The key is not allowed to use loyalty.
    404customer_not_found · redemption_not_found
    Nothing to spend for that shopper, or no such hold on this store.
    409loyalty_off · checkout_taken · hold_released · already_used
    The store has loyalty off, or the hold is no longer in a state for that call. Do not give the discount on hold_released.
    422not_redeemable
    More points than this order may take. The answer carries max_points.
    429rate_limited
    More than 120 calls a minute on one key.

  8. Testing

    Ask the store for a key on their development store, or write to hello@allidesk.com and we will set one up with a test customer who has points.

Didn't find it?

Write to hello@allidesk.com. A person replies, usually within one business day.