# Third-Party Integration Guide

Build integrations with Appstle Loyalty using our REST API. This guide covers authentication, common workflows, and the key endpoints you'll need.

## Authentication

There are two ways to authenticate with the Appstle Loyalty API:

### Merchant API Key

For direct API access, pass the merchant's API key in the header:

```
X-API-Key: <merchant-api-key>
```

Merchants create API keys from the Appstle Loyalty admin dashboard under **Settings → API Key Management**. Each key is scoped to a single Shopify store. Merchants can create multiple named keys (up to 10) and revoke them individually.

> **ℹ️ Note:** Direct API access requires an active API plan. Contact [support@appstle.com](mailto:support@appstle.com) for pricing.


### Partner Integration (Recommended for App-to-App)

If you're building a product that integrates with Appstle Loyalty (e.g., a helpdesk, CRM, review platform, or automation tool), use our **[Partner Integration Framework](/partner-integration)** for a seamless, zero-configuration experience.

With the Partner Integration Framework:

- Merchants connect with **one click** from either dashboard — no manual key exchange
- Your app receives a **scoped API token** automatically during the handshake
- Partner tokens **bypass the paid API plan** — merchants are never billed for partner API usage
- Tokens are **revoked automatically** when a merchant disconnects or uninstalls


👉 **[Read the full Partner Integration Guide →](/partner-integration)**

### Legacy Partner Key (X-App-Key)

For existing integrations that already use the `X-App-Key` header, this method continues to work:

```
X-API-Key: <merchant-api-key>
X-App-Key: <your-partner-key>
```

- **`X-API-Key`** — The merchant's API key, identifying which store to act on.
- **`X-App-Key`** — Your partner key, identifying your application.


> **Note:** New partners should use the [Partner Integration Framework](/partner-integration) instead. It provides a better merchant experience and eliminates the need for manual key exchange.


## Base URL

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

All admin endpoints are prefixed with `/api/external/`.

## Quick Start

### 1. Look Up a Customer's Loyalty Data

Retrieve a customer's full loyalty profile by Shopify customer ID or email:

```bash
# By customer ID
curl -X GET "https://loyalty-admin.appstle.com/api/external/customer-loyalty?shop=your-store.myshopify.com&customer_id=12345" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response includes:**

- Available, pending, and total credited points
- Current VIP tier and spent amount
- Referral link and completed referral count
- Active rewards and discount codes
- Social engagement status (Facebook, Instagram, etc.)


### 2. Get Point Transaction History

Retrieve a customer's full point transaction log:

```bash
curl -X GET "https://loyalty-admin.appstle.com/api/external/point-transaction-history/{customer_id}?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

### 3. Get Top Customers by Points

Retrieve your highest-value loyalty members:

```bash
curl -X GET "https://loyalty-admin.appstle.com/api/external/top-customers?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Point Management

### Add Points to a Customer

```bash
curl -X POST "https://loyalty-admin.appstle.com/api/external/add-points" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "your-store.myshopify.com",
    "customerId": 12345,
    "points": 100,
    "note": "VIP welcome bonus"
  }'
```

### Redeem Points for a Reward

```bash
curl -X POST "https://loyalty-admin.appstle.com/api/external/redeem-points" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "your-store.myshopify.com",
    "customerId": 12345,
    "pointRedeemRuleId": 42
  }'
```

### Approve Pending Transactions

For programs where points require approval before becoming available:

```bash
curl -X PUT "https://loyalty-admin.appstle.com/api/external/approve-pending-transactions?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId": 12345}'
```

## Customer Management

### Enroll a Customer

Add a customer to the loyalty program programmatically:

```bash
curl -X POST "https://loyalty-admin.appstle.com/api/external/enroll-customer" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "your-store.myshopify.com",
    "customerId": 12345,
    "customerEmail": "customer@example.com"
  }'
```

### Update a Customer's Birthday

Set a birthday to enable birthday reward automation:

```bash
curl -X PUT "https://loyalty-admin.appstle.com/api/external/update-customer-birth-date?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 12345,
    "birthDate": "1990-06-15"
  }'
```

## Store Credits

### Add Store Credits

```bash
curl -X POST "https://loyalty-admin.appstle.com/api/external/add-credits" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "your-store.myshopify.com",
    "customerId": 12345,
    "credits": 10.00,
    "note": "Goodwill credit"
  }'
```

## Discount Management

### Check a Discount Code

Validate a loyalty discount code before applying it at checkout:

```bash
curl -X PUT "https://loyalty-admin.appstle.com/api/external/check-discount?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discountCode": "REWARD-XXXX"}'
```

### Mark a Discount as Used

After a customer redeems their discount code at checkout, mark it as used:

```bash
curl -X PUT "https://loyalty-admin.appstle.com/api/external/update-discount-code-status?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discountCode": "REWARD-XXXX",
    "status": "USED"
  }'
```

## Program Configuration

### Get Point Earn Rules

Retrieve all active earn rules (point triggers) for a store:

```bash
curl -X GET "https://loyalty-admin.appstle.com/api/external/point-earn-rules?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Get Point Redeem Rules

Retrieve all active redemption options:

```bash
curl -X GET "https://loyalty-admin.appstle.com/api/external/point-redeem-rules?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Webhooks

Appstle Loyalty supports webhooks for real-time event notifications. See the [Webhooks documentation](/webhooks) for setup and available events.

Alternatively, use [Shopify Flow](/shopify-flow) to react to loyalty events within Shopify's native automation platform without managing webhook infrastructure.

## Rate Limits

API requests are rate-limited per store. If you receive a `429 Too Many Requests` response, implement exponential backoff before retrying.

## Common Integration Patterns

### Review Platform (e.g., Judge.me, Okendo, Yotpo)

The most common integration pattern for review platforms:

1. Customer submits a review on your platform
2. Your platform calls `POST /api/external/add-points` to credit points
3. Optionally, use Shopify Flow with the `reward-points-for-reviews` action for no-code setup


### CRM / Helpdesk (e.g., Gorgias, Zendesk)

Agents can look up loyalty data while handling tickets:

1. Call `GET /api/external/customer-loyalty` by customer email or ID to display loyalty status
2. Call `POST /api/external/add-points` or `POST /api/external/add-credits` to issue goodwill points
3. Call `GET /api/external/point-transaction-history/{customer_id}` to view recent activity


### Email / SMS Platform (e.g., Klaviyo, Omnisend)

Sync loyalty data for personalized campaigns:

1. Use webhooks to receive real-time point and tier events
2. Pull `GET /api/external/customer-loyalty` to enrich customer profiles with points balance, VIP tier, and referral link
3. Segment customers by tier (`currentVipTier`) or points range (`availablePoints`) for targeted campaigns


## Becoming a Partner

If you're building a product that integrates with loyalty programs (helpdesks, CRMs, review platforms, email tools, automation platforms), we'd love to work with you.

**What you get:**

- **Zero-friction merchant onboarding** via our [Partner Integration Framework](/partner-integration) — one-click connect
- **Scoped API tokens per merchant** — automatically provisioned, no manual key exchange
- **Bypasses the paid API plan** — merchants are never billed for partner API usage
- Technical support during integration
- Co-marketing opportunities
- Listed in our integration directory


**Current partners:** Judge.me, Klaviyo, Omnisend, Gorgias, and more.

**To apply:** Email [support@appstle.com](mailto:support@appstle.com) with:

- Your company name and product
- What Appstle Loyalty data your integration needs access to
- Expected API call volume per merchant


We typically onboard new partners within 1-2 business days. See the **[Partner Integration Guide](/partner-integration)** for the full technical walkthrough.

## Need Help?

- **Full API Reference:** See the [Admin APIs](/admin-api-swagger) and [Storefront APIs](/storefront-api-swagger) for complete endpoint documentation
- **Shopify Flow:** See the [Shopify Flow guide](/shopify-flow) for no-code automation
- **Partners:** [support@appstle.com](mailto:support@appstle.com)
- **Support:** [support@appstle.com](mailto:support@appstle.com)