AlliDeskHelp centre

AlliDesk API for apps

For a mobile app builder — or any app — to show a store's AlliDesk features in its own screens: sign-in with a one-time code, reviews, loyalty points and rewards, the wishlist and referrals, for the same customers and the same data as the store's website.

  1. How it fits together

    The store makes an API key in AlliDesk under Settings → Integrations → API keys, choosing A mobile app, and pastes it into your app's settings. Your server calls AlliDesk with it. Call /store first to see which features the store has on; sign the customer in with /auth and send their token with every call about them.

    GET https://app.allidesk.com/api/v1/store
Authorization: Bearer ald_live_…
X-Customer-Token: <token from /auth/verify>   (calls about a customer)

  2. Rules

    • Call from your server only. The key belongs to the store; it must never be put in an app or a web page, where anyone could read it.
    • Every call sends Authorization: Bearer <key>. Calls about a customer also send X-Customer-Token: <token> from /auth/verify.
    • An app with its own sign-in (Shopify customer accounts) can send X-Customer-Id: <Shopify customer ID> instead, with a key the store gave the customers scope.
    • Every answer is JSON. Errors look like { "error": { "code": "…", "message": "…" } }.
    • Features the store has switched off answer 409 module_off; read /store first and show only what is on.

  3. Scopes

    loyaltyRead a customer's points and rewards, and spend them — at a checkout or in an app
    reviewsRead product reviews and questions, and post new ones
    loginSign customers in with a one-time code to their phone or email
    wishlistRead and change a signed-in customer's wishlist
    referralsRead a signed-in customer's referral code, link and invites
    customersAct for any customer by their Shopify customer ID — only for an app that signs customers in itself

  4. Store

    Which AlliDesk features the store has switched on, so the app shows only those.

  5. GET /api/v1/store · The store and its features

    When the app starts, and when the merchant connects AlliDesk.

    Answer
    {
  "store": {
    "name": "Adynic",
    "shop": "adynic.myshopify.com",
    "domain": "adynic.in",
    "currency": "INR"
  },
  "modules": {
    "login": true,
    "reviews": true,
    "loyalty": true,
    "referrals": true,
    "wishlist": true,
    "reels": false
  },
  "key": {
    "scopes": [
      "login",
      "reviews",
      "loyalty",
      "wishlist",
      "referrals"
    ]
  }
}

  6. Sign-in

    The store's one-time-code sign-in, by email or Indian mobile number: the same account as on its website. The token it gives is sent as X-Customer-Token on every call about that customer.

  7. POST /api/v1/auth/send · Send a code

    The customer typed their email or mobile number. Scope login.

    identifierrequiredAn email, or a 10-digit Indian mobile number (with or without +91).
    Request
    {
  "identifier": "+91 98765 43210"
}
    Answer
    {
  "ok": true,
  "channel": "phone"
}

  8. POST /api/v1/auth/verify · Check the code

    The customer typed the code they received. Codes last 10 minutes; five tries. Scope login.

    identifierrequiredThe same identifier as for send.
    coderequiredThe 6-digit code.
    Request
    {
  "identifier": "+91 98765 43210",
  "code": "482913"
}
    Answer
    {
  "ok": true,
  "token": "cmh…​.1767225600.q2…",
  "customer_id": "7201928374650",
  "via": "shopify"
}

  9. POST /api/v1/auth/logout · Sign out

    The customer signs out of the app. The token stops working at once. Scope login. X-Customer-Token required.

    Answer
    {
  "ok": true
}

  10. GET /api/v1/customer · Who is signed in

    To greet the customer and fill forms. X-Customer-Token required.

    Answer
    {
  "customer": {
    "id": "7201928374650",
    "email": "riya@example.com",
    "phone": "+919876543210",
    "first_name": "Riya",
    "last_name": "Sharma",
    "points": 1200,
    "tier": "Gold"
  }
}

  11. Reviews

    Product reviews with photos, star summaries for product lists, helpful votes and questions.

  12. GET /api/v1/reviews?product=<id>&page=1&per_page=10&sort=recent · A product's reviews

    On the product page. sort is recent, helpful, rating_high, rating_low or pictures; rating=1…5 and photos=1 filter. Scope reviews.

    Answer
    {
  "product_id": "8123456789",
  "summary": {
    "count": 23,
    "average": 4.6,
    "buckets": {
      "1": 0,
      "2": 1,
      "3": 1,
      "4": 4,
      "5": 17
    }
  },
  "total": 23,
  "page": 1,
  "pages": 3,
  "reviews": [
    {
      "id": "cr1",
      "rating": 5,
      "title": "Loved the fit",
      "body": "Great quality…",
      "photos": [
        "https://…"
      ],
      "author": "Riya S",
      "verified": true,
      "date": "2026-09-20T10:00:00.000Z",
      "reply": null,
      "helpful": 4
    }
  ],
  "photos": [
    "https://…"
  ],
  "questions": [],
  "rules": {
    "can_write": true,
    "verified_only": true,
    "photos": true,
    "questions": true,
    "star_color": "#f5a524"
  }
}

  13. GET /api/v1/reviews/summary?products=<id>,<id> · Stars for many products

    On product lists: up to 100 products a call. Products without reviews are left out. Scope reviews.

    Answer
    {
  "ratings": {
    "8123456789": {
      "average": 4.6,
      "count": 23
    }
  }
}

  14. POST /api/v1/reviews · Write a review

    The customer sends a review. With the store's “verified buyers only” rule on, it needs X-Customer-Token of a customer who bought the product. Scope reviews. X-Customer-Token optional.

    product_idrequiredThe Shopify product ID.
    product_titlerequiredShown to the merchant.
    ratingrequired1 to 5.
    bodyrequiredThe review.
    titleA headline.
    photosUp to 6 https image URLs, already uploaded.
    name, emailFor a customer who isn't signed in.
    Request
    {
  "product_id": "8123456789",
  "product_title": "Blue Kurta",
  "rating": 5,
  "title": "Loved it",
  "body": "Great quality and fit."
}
    Answer
    {
  "ok": true,
  "status": "pending",
  "message": "Thank you. Your review will show once the store has read it."
}

  15. POST /api/v1/reviews/<id>/vote · Was this helpful?

    The shopper taps helpful or not. visitor is any stable ID for them. Scope reviews.

    Request
    {
  "helpful": true,
  "visitor": "device-7f3a"
}
    Answer
    {
  "ok": true,
  "yes": 5,
  "no": 0
}

  16. POST /api/v1/questions · Ask a question

    A shopper asks about a product; the store answers in AlliDesk. Scope reviews. X-Customer-Token optional.

    Request
    {
  "product_id": "8123456789",
  "product_title": "Blue Kurta",
  "body": "Is this cotton?",
  "name": "Arjun",
  "email": "arjun@example.com"
}
    Answer
    {
  "ok": true,
  "message": "Thanks. The store will answer this shortly."
}

  17. Loyalty

    The points programme, the customer's balance and tier, rewards, and points off an order. (Checkouts naming the customer by phone or email use the separate Loyalty API for checkouts.)

  18. GET /api/v1/loyalty/program · The programme

    For a guest: how points are earned and what they buy. Scope loyalty.

    Answer
    {
  "enabled": true,
  "signedIn": false,
  "pointsName": "Coins",
  "currency": "INR",
  "earnPerAmount": 100,
  "redeemRate": 0.25,
  "minRedeemPoints": 100,
  "waysToEarn": [],
  "rewards": [
    {
      "id": "rw1",
      "name": "₹100 off",
      "pointsCost": 400
    }
  ],
  "tiers": []
}

  19. GET /api/v1/loyalty/account · The customer's points

    On the account screen. Scope loyalty. X-Customer-Token required.

    Answer
    {
  "enabled": true,
  "signedIn": true,
  "balance": 1200,
  "pending": 150,
  "lifetime": 3400,
  "tier": {
    "name": "Gold"
  },
  "nextTier": {
    "name": "Platinum",
    "pointsAway": 600
  },
  "rewards": [
    {
      "id": "rw1",
      "name": "₹100 off",
      "pointsCost": 400,
      "canRedeem": true
    }
  ],
  "history": [],
  "codes": []
}

  20. POST /api/v1/loyalty/reward · Redeem a reward

    The customer spends points on a reward; the answer is a Shopify discount code. Scope loyalty. X-Customer-Token required.

    Request
    {
  "reward_id": "rw1"
}
    Answer
    {
  "ok": true,
  "code": "ALD-7KQ2M"
}

  21. GET /api/v1/loyalty/checkout?subtotal=1499 · Points this cart can take

    On the cart, to offer “Use 500 points”. Scope loyalty. X-Customer-Token required.

    Answer
    {
  "mode": "automatic",
  "points_name": "Coins",
  "balance": 1200,
  "max": 599,
  "max_value": 149.75,
  "rate": 0.25,
  "min_points": 100,
  "min_order": 499,
  "max_percent": 10,
  "applied": null
}

  22. POST /api/v1/loyalty/points · Use points on the cart

    The customer applies points. In automatic mode, put note on the Shopify cart as the allidesk_points attribute and Shopify's checkout takes the money off; in code mode, apply the code. Scope loyalty. X-Customer-Token required.

    Request
    {
  "points": 500,
  "subtotal": 1499
}
    Answer
    {
  "ok": true,
  "mode": "automatic",
  "note": "…",
  "cart_attribute": "allidesk_points",
  "amount": 125,
  "points": 500
}

  23. POST /api/v1/loyalty/unpoints · Take points off the cart

    The customer removes points before paying; they go back to their balance. Scope loyalty. X-Customer-Token required.

    Request
    {
  "note": "…"
}
    Answer
    {
  "ok": true,
  "message": null
}

  24. Wishlist

    The same wishlist as the store's website: saved in the app, seen on the web, and the other way round.

  25. GET /api/v1/wishlist · Saved products

    The wishlist screen, and to fill the hearts. Scope wishlist. X-Customer-Token required.

    Answer
    {
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": null,
      "title": "Blue Kurta",
      "handle": "blue-kurta",
      "image": "https://…",
      "price": 799,
      "list": "My wishlist"
    }
  ]
}

  26. POST /api/v1/wishlist · Save a product

    The customer taps the heart. Scope wishlist. X-Customer-Token required.

    Request
    {
  "product": {
    "id": "8123456789",
    "title": "Blue Kurta",
    "handle": "blue-kurta",
    "price": 799,
    "image": "https://…"
  }
}
    Answer
    {
  "ok": true
}

  27. DELETE /api/v1/wishlist?product=<id> · Remove a product

    The customer taps the heart again. Scope wishlist. X-Customer-Token required.

    Answer
    {
  "ok": true
}

  28. Referrals

    Invite-a-friend: the customer's own link, and the friend's discount when they arrive through it.

  29. GET /api/v1/referrals · The customer's link and invites

    The invite screen. locked is set when the store lets customers share only after a first order. Scope referrals. X-Customer-Token required.

    Answer
    {
  "locked": null,
  "code": "RIYA20",
  "link": "https://adynic.in/?ref=RIYA20",
  "share_message": "Get ₹100 off at Adynic: https://…",
  "friend_reward": "₹100 off their first order",
  "your_reward": "500 coins",
  "stats": {
    "clicks": 12,
    "joined": 3,
    "rewarded": 2,
    "pending": 1,
    "earned": "1,000 coins"
  },
  "referrals": []
}

  30. POST /api/v1/referrals/click · A friend arrived

    The app opened through a ?ref=CODE link. Counts the visit once per visitor and gives the friend's discount code. Scope referrals.

    Request
    {
  "code": "RIYA20",
  "visitor": "device-7f3a",
  "channel": "app"
}
    Answer
    {
  "ok": true,
  "code": "ALD-FRIEND-2K9"
}

  31. Errors

    400invalid_json · invalid_product · invalid_rating · invalid_identifier · …
    A field is missing or not in the shape shown.
    401unauthorized · store_uninstalled · customer_required · customer_token_invalid
    No key or a revoked one, the store removed AlliDesk, or the call needs a signed-in customer.
    403forbidden
    The key doesn't have the scope this call needs.
    409module_off
    The store has that feature switched off in AlliDesk. Hide it in the app.
    422review_refused · reward_refused · points_refused · referral_refused
    The store's rules said no; the message says why and can be shown to the customer.
    429rate_limited
    More than 600 calls a minute on one key.

  32. Testing

    Ask the store for a key on their development store — turning on sign-in test mode in AlliDesk makes /auth/send answer with the code, so no phone is needed — or write to hello@allidesk.com.

Didn't find it?

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