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

# Loyalty & Rewards API overview

> REST API reference for Pcnaid Loyalty & Rewards — public v1 endpoints, authentication, and request/response patterns.

# Loyalty & Rewards API overview

The public REST API is available at `/api/public/v1/*`. Endpoints require a tenant-bound API key. API access is available on the **Scale** plan and above.

## Authentication

Include the API key in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: your-api-key" \
  "${APP_ORIGIN:?Set APP_ORIGIN}/api/public/v1/customers"
```

Set `APP_ORIGIN` to the app origin shown with your API key in the app settings, without a trailing slash.

* Invalid or cross-shop keys return `401`.
* Authenticated keys missing an endpoint scope return `403`.
* Custom-event ingestion requires an API key with the `events:write` scope.

## Customers

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/customers` | List loyalty customers |
| GET | `/api/public/v1/customers/:customerId` | Get a single customer's loyalty profile |
| POST | `/api/public/v1/enroll-customer` | Enroll a customer in the loyalty program |

## Points

| Method | Endpoint | Description |
| - | - | - |
| POST | `/api/public/v1/add-points` | Award points to a customer |
| GET | `/api/public/v1/points/:customerId` | Get a customer's point balance |
| POST | `/api/public/v1/approve-pending` | Approve pending points for a customer |

## Credits (store credit)

| Method | Endpoint | Description |
| - | - | - |
| POST | `/api/public/v1/add-credits` | Add store credit to a customer's account |

## Rewards and redemption

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/rewards` | List available rewards |
| GET | `/api/public/v1/redeem-rules` | Get redemption rules |
| POST | `/api/public/v1/redeem-points` | Redeem points for a reward |
| GET | `/api/public/v1/redemptions` | List customer redemptions |
| GET | `/api/public/v1/check-discount` | Check a discount code status |

## Earning rules

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/earn-rules` | List earning rules |

## Events (custom events)

| Method | Endpoint | Description |
| - | - | - |
| POST | `/api/public/v1/events` | Submit a custom event. Requires `events:write` scope. Reusing an event ID returns the original outcome. |

## Analytics and insights

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/top-customers` | Top customers leaderboard |
| GET | `/api/public/v1/benchmark` | KPI benchmarking data |
| GET | `/api/public/v1/churn-risk` | Churn risk scoring |

## Customer management

| Method | Endpoint | Description |
| - | - | - |
| PUT | `/api/public/v1/update-birth-date` | Update a customer's birth date |
| PUT | `/api/public/v1/update-discount-status` | Update a discount code status |
| PUT | `/api/public/v1/update-discount` | Update a discount code |

## B2B and households

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/b2b` | B2B company data |
| GET | `/api/public/v1/household` | Household wallet data |

## Transaction history

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/transaction-history/:customerId` | Get a customer's point transaction history |

## Widget labels

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/public/v1/widget-labels` | Get storefront widget label translations |

## Storefront proxy API

The signed app proxy at `/apps/loyalty/*` (forwarded to `/api/loyalty/*`) provides:

* Customer visit tracking, self-enrollment, loyalty status updates.
* Points history, redemption, referral data, social action claims.
* Review submission and product review details.
* Apple Wallet and Google Wallet pass delivery.
* SSE notifications for real-time updates.
* Household management.
* Transaction history by shop.
* B2B company endpoints.

## SDK and integrations

* **JavaScript SDK** — TypeScript SDK for headless storefronts (`@shopify-loyalty/sdk`).
* **Hydrogen helpers** — server-side API client for Shopify Hydrogen stores.
* **Shopify Flow** — 10 triggers and 6 actions for points, tier, and reward automation.

## Health check

```bash theme={null}
curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/healthz"
```

Returns HTTP 200 when the app is healthy.

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [Loyalty & Rewards](https://docs.pcnaid.com/nodes/shopify/loyalty-rewards/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/loyalty-rewards/developer/index) › API › Loyalty & Rewards API overview


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.