Quickstart

#What you will build

A LARM app is a server you own that connects to a merchant's store with the merchant's permission. The merchant installs the app and approves a specific set of scopes. Your server then receives an access token that can read and write only what the merchant approved, and signed webhooks reach it for every order, payment and delivery.

Every API call goes through one base URL:

https://larm.sa/stores/{storeId}/v1

#1. Create a developer account and organization

Sign in to the Developer Portal and create an organization with your company name. The organization owns your apps, and you can invite your team to it with different roles.

#2. Create an app draft

On the My apps tab, click Create app and fill in:

After you save, your Client ID appears on the "Connect your app" card. Generate the client secret from the Access tab and store it immediately; it is shown only once.

#3. Install the app on a development store

Create a development store from the Development stores tab, then install the version of your app approved for development on it. See Development stores for details.

On install, LARM opens your launch URL with larm_intent=install and larm_store_id. Verify the URL with Verify a launch URL, then send the merchant to the authorization page as described in Authentication.

#4. Exchange the code for an access token

curl -X POST "https://larm.sa/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=$CODE&redirect_uri=https://app.example.com/larm/callback&code_verifier=$VERIFIER"

The response is a token pair: an access_token valid for 15 minutes, and a refresh_token valid for 30 days that is replaced on every refresh.

#5. Call the API

curl "https://larm.sa/stores/$STORE_ID/v1/orders?payment_status=paid&limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "ord_8Kd2",
      "number": 10482,
      "status": "processing",
      "payment_status": "paid",
      "currency": "SAR",
      "totals": { "subtotal": "180.00", "discount": "0.00", "shipping": "25.00", "total": "205.00" },
      "items": [{ "product_id": "311", "name": "Top-up card 100 SAR", "kind": "digital", "quantity": 2, "unit_price": "90.00", "total": "180.00" }],
      "created_at": "2026-10-15T09:12:44Z"
    }
  ],
  "meta": { "next_cursor": null, "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a" }
}

Call [GET /me](/api/me) first if you want to confirm the token and its scopes before anything else.

#6. Subscribe to webhooks

Instead of polling the API every minute, subscribe once and receive every new order as soon as it is created:

curl -X POST "https://larm.sa/stores/$STORE_ID/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_url":"https://app.example.com/larm/webhooks","event_types":["order.created","order.paid"],"payload_version":1}'

Store the secret from the response; you use it to verify the signature of every webhook. See Webhooks for details.

#Next steps

• Read API fundamentals for the response envelope, pagination and idempotency keys.
• See Working with orders for order and payment statuses and customer data.
• When you are ready, submit the version for review as described in App review & publishing.