Developers

Guides

Markdown

Customers and loyalty

Find a customer by phone or email, add new customers safely, follow changes, and read and adjust loyalty points.

What your app needs

You want toScopeWhere
List customers and find onecustomers.list:readGET /customers
Add a customer and change their namecustomers.list:writePOST /customers, PATCH /customers/{id}
Read a customer's pointsloyalty:readGET /customers/{id}/loyalty
Add or remove pointsloyalty:writePOST /customers/{id}/loyalty-adjustments
Read a customer's ordersorders:readGET /orders?customer_id=5821

If your app only needs the customer of an order, customers:read is enough, and you do not need the whole list.

Find a customer

cURL
curl "https://larm.sa/stores/$STORE_ID/v1/customers?phone=0512345678" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

phone accepts any Saudi form: 05…, 5…, 9665… or +9665…. Answers always give the phone as +9665…, or null when the number is not valid. email is an exact match, and search looks in the name and email.

Keep in sync

Read the whole list once, page by page, oldest first. Then subscribe to customer.created, customer.updated and customer.deleted. When a customer is deleted, delete what you hold about them.

Every read of the list goes into the merchant's log.

Add a customer

cURL
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","phone":"0512345678","first_name":"Sara","last_name":"Alotaibi"}'
  • The email is required. A customer who already has this email or phone returns 409 CUSTOMER_EXISTS, so find them first.
  • The owner of the email takes over. The new account has no password and is not active. It becomes a real account when that person registers on the store and proves the email with a code. Your app can never open someone else's orders or points this way.
  • Only names can change. A phone or email decides who can sign in, so only the customer changes them.

Loyalty points

Points exist when the merchant's plan includes the loyalty program and the merchant turned it on. Otherwise adding points returns 409 LOYALTY_DISABLED.

cURL
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/customers/5821/loyalty-adjustments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"points":50,"reason":"Bonus for a product review"}'
  • points is positive to add and negative to remove. Removing more than the balance returns 409 INSUFFICIENT_LOYALTY_POINTS.
  • reason shows in the customer's points history.
  • A resend with the same Idempotency-Key does not add the points twice.
  • The customer spends points at checkout. Your app cannot spend them for the customer.

Not available

  • Customer groups and tags.
  • Marketing consent. The store does not record it per customer, so ask for it in your own app before you send marketing.
  • The customer wallet, reading or changing it.

    ↑↓ moveEnter openEsc close