> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Appstle Loyalty API

> Create an API key, retrieve a customer's loyalty profile with points and VIP tier, then credit points to their account — all in under five minutes.

This guide walks you through the three steps needed to make your first Appstle Loyalty API calls: getting a key, reading a customer's loyalty data, and adding points. By the end you will have a working integration you can build on.

## Prerequisites

* An active Appstle Loyalty subscription on your Shopify store
* Access to the Appstle admin panel
* A Shopify customer ID to test with (find one in your Shopify admin under **Customers**)

## Step 1 — Get your API key

<Steps>
  <Step title="Open API Key Management">
    In your Appstle admin panel, go to **Settings → API Key Management**.
  </Step>

  <Step title="Create a key">
    Click **Create New Key**. Give it a name like `Quickstart test`, then click **Save**.
  </Step>

  <Step title="Copy the key">
    Copy the displayed key immediately. It is only shown once. Store it as an environment variable:

    ```bash theme={null}
    export APPSTLE_API_KEY="apst_your-api-key-here"
    export SHOP="your-store.myshopify.com"
    ```
  </Step>
</Steps>

<Warning>
  Never put your API key in client-side code. All requests must be made from a server you control.
</Warning>

## Step 2 — Retrieve customer loyalty data

Call `GET /api/external/customer-loyalty` with your store domain and a Shopify customer ID. Replace `12345` with a real customer ID from your store.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET \
    "https://loyalty-admin.appstle.com/api/external/customer-loyalty?shop=${SHOP}&customer_id=12345" \
    -H "X-API-Key: ${APPSTLE_API_KEY}"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://loyalty-admin.appstle.com/api/external/customer-loyalty?shop=${process.env.SHOP}&customer_id=12345`,
    { headers: { 'X-API-Key': process.env.APPSTLE_API_KEY } }
  );
  const loyalty = await response.json();
  console.log(loyalty);
  ```

  ```python Python theme={null}
  import httpx, os

  r = httpx.get(
      'https://loyalty-admin.appstle.com/api/external/customer-loyalty',
      params={'shop': os.environ['SHOP'], 'customer_id': '12345'},
      headers={'X-API-Key': os.environ['APPSTLE_API_KEY']},
  )
  print(r.json())
  ```
</CodeGroup>

A successful response looks like this:

```json theme={null}
{
  "availablePoints": 1250,
  "pendingPoints": 150,
  "creditedPoints": 1400,
  "storeCreditBalance": 25.0,
  "currentVipTier": "Gold",
  "customerStatus": "ACTIVE"
}
```

| Field                | Description                                   |
| -------------------- | --------------------------------------------- |
| `availablePoints`    | Points the customer can redeem right now      |
| `pendingPoints`      | Points earned but not yet approved            |
| `creditedPoints`     | Total lifetime points ever credited           |
| `storeCreditBalance` | Monetary store credit balance                 |
| `currentVipTier`     | Active VIP tier name, or empty string if none |
| `customerStatus`     | `ACTIVE` or `INACTIVE`                        |

<Tip>
  If you get a `404`, the customer is not yet enrolled in the loyalty program. See [Step 3 of the integration guide](/loyalty/integration-guide#customer-management) to enroll them first.
</Tip>

## Step 3 — Add points to the customer

Call `POST /api/external/add-points` to credit points. Include a `note` so the transaction is clearly labeled in the customer's history.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST \
    "https://loyalty-admin.appstle.com/api/external/add-points" \
    -H "X-API-Key: ${APPSTLE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "shop": "your-store.myshopify.com",
      "customerId": 12345,
      "points": 100,
      "note": "Quickstart test credit"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://loyalty-admin.appstle.com/api/external/add-points',
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.APPSTLE_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        shop: process.env.SHOP,
        customerId: 12345,
        points: 100,
        note: 'Quickstart test credit',
      }),
    }
  );
  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import httpx, os, json

  r = httpx.post(
      'https://loyalty-admin.appstle.com/api/external/add-points',
      headers={
          'X-API-Key': os.environ['APPSTLE_API_KEY'],
          'Content-Type': 'application/json',
      },
      content=json.dumps({
          'shop': os.environ['SHOP'],
          'customerId': 12345,
          'points': 100,
          'note': 'Quickstart test credit',
      }),
  )
  print(r.json())
  ```
</CodeGroup>

Call `GET /api/external/customer-loyalty` again and you will see `availablePoints` increased by 100.

## What to build next

<Columns cols={2}>
  <Card title="Full integration guide" icon="plug" href="/loyalty/integration-guide">
    Every endpoint: point management, customer enrollment, rewards, store credits, and program configuration.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/loyalty/webhooks">
    Receive real-time notifications for points earned, VIP tier changes, and referral completions.
  </Card>

  <Card title="Shopify Flow" icon="zap" href="/loyalty/shopify-flow">
    Trigger loyalty actions from any Shopify Flow workflow without writing API code.
  </Card>
</Columns>