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

# Appstle Loyalty: Points, VIP Tiers & Referrals

> Appstle Loyalty provides Admin and Storefront REST APIs to build points programs, VIP tiers, and referrals on Shopify. Learn which API fits your use case.

Appstle Loyalty is a complete loyalty and rewards platform for Shopify stores. Once you install the app, Appstle exposes two REST API surfaces so you can build anything from simple points programs to multi-tier VIP schemes with referrals, reviews, and store credits on top of your loyalty data.

## Available APIs

Appstle Loyalty exposes two REST API surfaces. Pick the one that matches where your code runs:

* **Admin API** — server-side, authenticated with `X-API-Key`. For backend integrations, mobile apps, automation, and admin dashboards. Browse the full reference under **Admin API** in the sidebar.
* **Storefront API** — customer-facing, accessed through Shopify App Proxy. For loyalty widgets and self-service portals on your storefront. Browse the full reference under **Storefront API** in the sidebar.

## Which API should you use?

<Tabs>
  <Tab title="Use the Admin API when…">
    * You are building a **server-side integration** (backend service, CRM connector, helpdesk plugin)
    * You are building a **mobile app** (iOS or Android)
    * You need to **credit or debit points programmatically** on behalf of merchants
    * You want to run **bulk operations** or scheduled automation
    * You are building an **admin dashboard** or reporting tool
    * Your code runs **anywhere outside a customer's browser** on the storefront

    <Info>
      Admin API requests require an `X-API-Key` header. Keys are created in the Appstle dashboard under **Settings → API Key Management**. Never expose keys in client-side code.
    </Info>
  </Tab>

  <Tab title="Use the Storefront API when…">
    * You are building a **custom loyalty portal** hosted on your Shopify storefront
    * You want customers to **earn and redeem points** themselves (widgets, referral pages, review forms)
    * Your code runs **inside the storefront** with a logged-in customer session
    * You are customizing the loyalty widget **theme or appearance**

    <Warning>
      Storefront APIs run exclusively through Shopify's App Proxy and require the customer to be logged in. They will not accept API key authentication and cannot be called from a backend server.
    </Warning>
  </Tab>
</Tabs>

## Key features

<CardGroup cols={2}>
  <Card title="Point management" icon="coins">
    Credit and debit points for purchases, reviews, social actions, birthdays, and custom activities. Access full transaction history.
  </Card>

  <Card title="VIP tiers" icon="crown">
    Define spend or points thresholds for Bronze, Silver, Gold, Platinum, or any tier structure. Automatically promote and demote customers.
  </Card>

  <Card title="Referral program" icon="user-plus">
    Generate unique referral links, track accepted referrals, and reward both the referrer and the referred customer.
  </Card>

  <Card title="Product reviews" icon="star">
    Let customers submit reviews and earn points. Display ratings via Shopify metafields compatible with native rich results.
  </Card>

  <Card title="Store credits" icon="wallet">
    Issue monetary store credit as an alternative to discount codes. Balances are tracked separately from loyalty points.
  </Card>

  <Card title="Rewards & discounts" icon="tag">
    Convert points into Shopify discount codes. Validate and mark codes as used from your own checkout flow.
  </Card>
</CardGroup>

## Key concepts

<AccordionGroup>
  <Accordion title="Points lifecycle">
    Points move through three states: **pending** (earned but awaiting approval), **available** (redeemable), and **credited** (total lifetime points earned). Your program configuration determines whether points are credited immediately or held in a pending state for review.
  </Accordion>

  <Accordion title="VIP tiers">
    Tiers are assigned automatically when a customer crosses a configured spend or points threshold. Each tier can carry a name tag and any number of additional Shopify customer tags. Tags are swapped automatically on tier changes — there is always at most one active tier per customer.
  </Accordion>

  <Accordion title="Referrals">
    Every enrolled customer receives a unique referral link. When a referred customer makes a qualifying purchase, both parties receive rewards as defined in your referral configuration. Referral relationships are recorded permanently as Shopify customer tags.
  </Accordion>

  <Accordion title="Store credits">
    Store credits are a monetary balance separate from points. They are applied at checkout and tracked in `storeCreditBalance` on the customer loyalty profile. Credits can be issued via the Admin API or through Shopify Flow.
  </Accordion>

  <Accordion title="Partner integrations">
    Third-party apps (helpdesks, CRMs, review platforms, email tools) can connect to Appstle Loyalty through the Partner Integration Framework. Partners receive a scoped API token per merchant with no manual key exchange. Merchants connect and disconnect with one click.
  </Accordion>
</AccordionGroup>

## Base URL

All Admin API endpoints use:

```
https://loyalty-admin.appstle.com
```

Storefront API endpoints are accessed through your store's Shopify App Proxy — no separate base URL is needed.

## HTTP status codes

All API responses use standard HTTP status codes.

| Code  | Meaning                                    |
| ----- | ------------------------------------------ |
| `200` | Success                                    |
| `201` | Resource created                           |
| `400` | Bad request — invalid parameters           |
| `401` | Unauthorized — missing or invalid API key  |
| `403` | Forbidden — key lacks required permissions |
| `404` | Not found                                  |
| `429` | Rate limit exceeded                        |
| `500` | Server error                               |

Error responses follow this shape:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "status": 401
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/loyalty/authentication">
    Create API keys and learn how to authenticate every request.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/loyalty/quickstart">
    Get your API key, make your first request, and add points in under five minutes.
  </Card>

  <Card title="Integration guide" icon="book" href="/loyalty/integration-guide">
    Full walkthrough of every endpoint category with working curl examples.
  </Card>

  <Card title="Webhooks" icon="bell" href="/loyalty/webhooks">
    Receive real-time notifications for points, tier changes, and referrals.
  </Card>
</CardGroup>