# Third-Party Integration Guide

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

## Authentication

### Merchant API Key

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


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

Merchants create and manage API keys from the Appstle Memberships admin dashboard under **Settings → API Key Management**. Each key is scoped to a single Shopify store.

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


### Partner Integration Key

If you're building a product that integrates with Appstle Memberships (CRM, helpdesk, email platform, automation tool), you can apply for a **Partner Key**:


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

- **`X-API-Key`** — The merchant's API key (generated in Appstle and entered in your integration settings)
- **`X-App-Key`** — Your partner key, provisioned by Appstle — the same key for all merchants using your integration


Partner integrations bypass the paid plan requirement. To apply, email [partners@appstle.com](mailto:partners@appstle.com).

## Base URL


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

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

## Key Endpoints

### Look Up a Member's Membership Contracts

Retrieve all active membership contracts for a customer:


```bash
curl -X GET "https://membership-admin.appstle.com/api/external/v2/membership-contracts?shop=your-store.myshopify.com&customerId=12345" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response:**


```json
{
  "content": [
    {
      "id": 1001,
      "status": "ACTIVE",
      "membershipPlanName": "Gold Member",
      "nextBillingDate": "2026-03-01",
      "billingCycleType": "MONTHLY",
      "startDate": "2026-01-01",
      "endDate": null
    }
  ],
  "totalElements": 1
}
```

### Check if a Customer is an Active Member

A common use case — verify membership before granting access to gated content or discounts:


```bash
curl -X GET "https://membership-admin.appstle.com/api/external/v2/membership-status?shop=your-store.myshopify.com&customerId=12345" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Get Membership Contract Details

Retrieve full details for a specific membership contract:


```bash
curl -X GET "https://membership-admin.appstle.com/api/external/v2/membership-contracts/{contractId}?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

### List All Membership Plans

Retrieve all available membership plans for a store:


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

### Cancel a Membership

Cancel a customer's membership programmatically:


```bash
curl -X POST "https://membership-admin.appstle.com/api/external/v2/membership-contracts/{contractId}/cancel?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested cancellation via support ticket"}'
```

### Pause a Membership

Pause a membership for a customer:


```bash
curl -X POST "https://membership-admin.appstle.com/api/external/v2/membership-contracts/{contractId}/pause?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Resume a Paused Membership

Reactivate a paused membership:


```bash
curl -X POST "https://membership-admin.appstle.com/api/external/v2/membership-contracts/{contractId}/resume?shop=your-store.myshopify.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

See the full [Admin API Reference](/admin-api-swagger) for the complete list of endpoints, request parameters, and response schemas.

## Common Integration Patterns

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

Help agents verify and manage memberships while handling support tickets:

1. Look up member status by customer ID from the Shopify customer context
2. Display active plan, billing date, and status in the agent sidebar
3. Cancel, pause, or update memberships directly from the helpdesk with a single API call
4. Log actions back to Appstle for audit trail


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

Sync membership data for lifecycle automations:

1. Use [Webhooks](/webhooks) to receive real-time membership events (`membership.created`, `membership.cancelled`, etc.)
2. Enrich customer profiles with membership tier, plan name, and next billing date
3. Trigger flows based on events:
  - `membership.billing-failure` → "Update your payment method" dunning sequence
  - `membership.cancelled` → Win-back offer sequence
  - `membership.created` → Welcome onboarding sequence
  - `membership.expired` → Re-engagement campaign


### Access Control / Gated Content

Control access to content, pages, or products based on active membership:

1. On page load, call the membership status endpoint via server-side API
2. Check `status === "ACTIVE"` and verify the plan includes access to the requested resource
3. Gate or unlock accordingly — redirect non-members to the plan selection page
4. Cache membership status per session to avoid rate limits


### Analytics / BI Tools

Pull membership data for reporting:

1. Use the membership contracts list endpoint with pagination to export all contracts
2. Filter by `status` to track active vs. churned members
3. Use `nextBillingDate` and `billingCycleType` for MRR/ARR projections
4. Combine with [webhook](/webhooks) events to track churn events in real time


## Rate Limits

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

## Response Format

All responses use standard HTTP status codes:

| Status Code | Meaning |
|  --- | --- |
| `200` | Success |
| `201` | Created |
| `400` | Bad Request — invalid parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — key lacks permission |
| `404` | Not Found |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Server Error |


## Becoming a Partner

Building a product that integrates with Appstle Memberships? Apply for a Partner Key to enable seamless merchant integrations without requiring paid API plans.

Email [partners@appstle.com](mailto:partners@appstle.com) with your company name, product description, and expected API volume.

## Resources

- **Full API Reference:** [Admin APIs](/admin-api-swagger) · [Customer Portal APIs](/storefront-api-swagger)
- **Webhooks:** [Real-time event notifications](/webhooks)
- **Shopify Flow:** [No-code automation](/shopify-flow)
- **Support:** [support@appstle.com](mailto:support@appstle.com)
- **Partners:** [partners@appstle.com](mailto:partners@appstle.com)