# Quickstart

Go from a developer account to your first successful API call on a development store, step by step.

## 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:

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

> Keep access tokens and the client secret on your server. Never send them to a browser or ship them in a mobile app.

## 1. Create a developer account and organization

Sign in to the [Developer Portal](https://larm.sa/developers) 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:

| Field | Example | Why |
|---|---|---|
| Launch URL `launch_url` | `https://app.example.com/larm/launch` | The merchant opens it from the dashboard, and it receives the `larm_*` parameters |
| Redirect URLs | `https://app.example.com/larm/callback` | The authorization code is returned here after the merchant approves |
| Webhook URL | `https://app.example.com/larm/webhooks` | Store webhooks are delivered here (optional) |
| Uninstall & privacy webhook URL | `https://app.example.com/larm/privacy` | Installation webhooks and data-deletion requests are delivered here |
| Scopes | `orders:read` and `products:read` | Only what your app needs, with a justification for each scope |

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](/guides/test-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](/api/oauth-launch-verify), then send the merchant to the authorization page as described in [Authentication](/guides/authentication).

## 4. Exchange the code for an access token

```bash
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

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

```json
{
  "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:

```bash
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](/guides/webhooks) for details.

## Next steps

- Read [API fundamentals](/guides/requests) for the response envelope, pagination and idempotency keys.
- See [Working with orders](/guides/orders) for order and payment statuses and customer data.
- When you are ready, submit the version for review as described in [App review & publishing](/guides/publishing).