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

# API Reference

# API Reference

The Stackfront backend exposes a REST API that the SDK communicates with. You can also call these endpoints directly if you need to integrate outside of the React Native SDK.

## Base URL

| Environment | URL                                 |
| ----------- | ----------------------------------- |
| Sandbox     | `https://api.sandbox.stackfront.io` |
| Production  | `https://api.stackfront.io`         |

## Authentication

There are two authentication modes depending on the endpoint:

### SDK Endpoints (mobile app → Stackfront API)

```
X-Developer-Api-Key: sf_test_xxx or sf_live_xxx
X-Shop-Domain: mystore.myshopify.com
```

### Merchant Endpoints (Shopify admin → Stackfront API)

Authenticated via Shopify session OAuth token (handled automatically by the Shopify app).

### Developer Endpoints (developer dashboard → Stackfront API)

Authenticated via JWT bearer token obtained from the OTP-based auth flow.

## Content-Type

All requests and responses use `application/json`.

## Errors

Standard error response format:

```json theme={null}
{
  "message": "Human-readable error description"
}
```

HTTP status codes:

| Code  | Meaning                                              |
| ----- | ---------------------------------------------------- |
| `200` | Success                                              |
| `400` | Bad request (validation error)                       |
| `401` | Unauthorized (missing or invalid auth)               |
| `403` | Forbidden (feature not enabled or sandbox limit hit) |
| `404` | Not found                                            |
| `422` | Unprocessable entity (business rule violation)       |
| `429` | Rate limited                                         |
| `500` | Internal server error                                |

## Rate Limits

| Endpoint Group | Limit                                              |
| -------------- | -------------------------------------------------- |
| SDK config     | 50 requests/minute per developer API key (sandbox) |
| SDK events     | 100 requests/minute                                |
| All others     | 1000 requests/minute                               |

## Pagination

List endpoints use `page` and `pageSize` query parameters:

| Parameter  | Default | Description              |
| ---------- | ------- | ------------------------ |
| `page`     | `1`     | Page number (1-indexed)  |
| `pageSize` | `20`    | Items per page (max 100) |

## Endpoints

### SDK Configuration

| Method | Path                 | Description                                                               |
| ------ | -------------------- | ------------------------------------------------------------------------- |
| `GET`  | `/api/v1/sdk/config` | Fetch SDK configuration (branding, feature flags, storefront token, etc.) |

### SDK Push Notifications

| Method | Path                                    | Description                              |
| ------ | --------------------------------------- | ---------------------------------------- |
| `POST` | `/api/v1/sdk/devices/register`          | Register a device for push notifications |
| `POST` | `/api/v1/sdk/devices/unsubscribe`       | Unsubscribe a device from push           |
| `POST` | `/api/v1/sdk/devices/link-customer`     | Link a device to a customer account      |
| `GET`  | `/api/v1/sdk/notifications/preferences` | Get notification preferences             |
| `PUT`  | `/api/v1/sdk/notifications/preferences` | Update notification preferences          |
| `POST` | `/api/v1/sdk/notifications/track-open`  | Track a push notification open           |

### SDK Events & Analytics

| Method | Path                 | Description              |
| ------ | -------------------- | ------------------------ |
| `POST` | `/api/v1/sdk/events` | Track an analytics event |

### SDK Loyalty

| Method | Path                                 | Description                     |
| ------ | ------------------------------------ | ------------------------------- |
| `GET`  | `/api/v1/sdk/loyalty/account`        | Get customer loyalty account    |
| `GET`  | `/api/v1/sdk/loyalty/transactions`   | Get loyalty transaction history |
| `POST` | `/api/v1/sdk/loyalty/redeem`         | Redeem loyalty points           |
| `GET`  | `/api/v1/sdk/loyalty/referral`       | Get customer referral link      |
| `POST` | `/api/v1/sdk/loyalty/referral/track` | Track a referral conversion     |

### SDK Reviews

| Method | Path                               | Description                       |
| ------ | ---------------------------------- | --------------------------------- |
| `GET`  | `/api/v1/sdk/reviews/{productId}`  | Get reviews for a product         |
| `POST` | `/api/v1/sdk/reviews`              | Submit a review                   |
| `POST` | `/api/v1/sdk/reviews/{id}/media`   | Upload review media (image/video) |
| `POST` | `/api/v1/sdk/reviews/{id}/helpful` | Mark a review as helpful          |

### SDK Social Proof

| Method | Path                                           | Description                         |
| ------ | ---------------------------------------------- | ----------------------------------- |
| `POST` | `/api/v1/sdk/social-proof/product-view`        | Track a product view                |
| `GET`  | `/api/v1/sdk/social-proof/product/{productId}` | Get social proof data for a product |

### SDK Stories

| Method | Path                                | Description                          |
| ------ | ----------------------------------- | ------------------------------------ |
| `GET`  | `/api/v1/sdk/stories`               | Get active story groups with stories |
| `POST` | `/api/v1/sdk/stories/viewed`        | Mark a story as viewed               |
| `POST` | `/api/v1/sdk/stories/tapped`        | Track a story tap                    |
| `POST` | `/api/v1/sdk/stories/poll-response` | Submit a story poll response         |

### SDK Integrations

| Method | Path                                         | Description                                               |
| ------ | -------------------------------------------- | --------------------------------------------------------- |
| `GET`  | `/api/v1/sdk/integrations/{slug}/{dataType}` | Get integration data (e.g., loyalty points from Smile.io) |

### Merchant Auth

| Method | Path                     | Description            |
| ------ | ------------------------ | ---------------------- |
| `GET`  | `/auth/shopify`          | Initiate Shopify OAuth |
| `GET`  | `/auth/shopify/callback` | Shopify OAuth callback |

### Merchant Status & Setup

| Method | Path                                    | Description                       |
| ------ | --------------------------------------- | --------------------------------- |
| `GET`  | `/api/v1/merchants/me/status`           | Get merchant setup status         |
| `POST` | `/api/v1/merchants/me/register`         | Complete merchant registration    |
| `POST` | `/api/v1/merchants/me/storefront-token` | Save Shopify Storefront API token |
| `POST` | `/api/v1/merchants/me/reprovision`      | Re-run provisioning               |

### Merchant Billing

| Method | Path                                   | Description                   |
| ------ | -------------------------------------- | ----------------------------- |
| `GET`  | `/api/v1/merchants/me/plans`           | List available merchant plans |
| `GET`  | `/api/v1/merchants/me/billing/status`  | Get billing status            |
| `POST` | `/api/v1/merchants/me/billing/upgrade` | Upgrade merchant plan         |
| `GET`  | `/billing/confirm`                     | Billing confirmation callback |

### Merchant Branding & Content

| Method   | Path                                         | Description            |
| -------- | -------------------------------------------- | ---------------------- |
| `GET`    | `/api/v1/merchants/me/branding`              | Get branding config    |
| `PATCH`  | `/api/v1/merchants/me/branding`              | Update branding config |
| `POST`   | `/api/v1/merchants/me/branding/logo`         | Upload logo            |
| `POST`   | `/api/v1/merchants/me/branding/splash`       | Upload splash screen   |
| `GET`    | `/api/v1/merchants/me/home-layout`           | Get home layout        |
| `PUT`    | `/api/v1/merchants/me/home-layout`           | Update home layout     |
| `GET`    | `/api/v1/merchants/me/banners`               | List banners           |
| `POST`   | `/api/v1/merchants/me/banners`               | Create banner          |
| `PUT`    | `/api/v1/merchants/me/banners/{id}`          | Update banner          |
| `DELETE` | `/api/v1/merchants/me/banners/{id}`          | Delete banner          |
| `PATCH`  | `/api/v1/merchants/me/banners/reorder`       | Reorder banners        |
| `GET`    | `/api/v1/merchants/me/popups`                | List popups            |
| `POST`   | `/api/v1/merchants/me/popups`                | Create popup           |
| `PUT`    | `/api/v1/merchants/me/popups/{id}`           | Update popup           |
| `DELETE` | `/api/v1/merchants/me/popups/{id}`           | Delete popup           |
| `GET`    | `/api/v1/merchants/me/announcements`         | List announcements     |
| `POST`   | `/api/v1/merchants/me/announcements`         | Create announcement    |
| `PUT`    | `/api/v1/merchants/me/announcements/{id}`    | Update announcement    |
| `DELETE` | `/api/v1/merchants/me/announcements/{id}`    | Delete announcement    |
| `PATCH`  | `/api/v1/merchants/me/announcements/reorder` | Reorder announcements  |
| `GET`    | `/api/v1/merchants/me/features`              | Get feature flags      |
| `PATCH`  | `/api/v1/merchants/me/features`              | Update feature flags   |

### Merchant Campaigns & Push

| Method   | Path                                                   | Description               |
| -------- | ------------------------------------------------------ | ------------------------- |
| `GET`    | `/api/v1/merchants/me/campaigns`                       | List push campaigns       |
| `POST`   | `/api/v1/merchants/me/campaigns`                       | Create campaign           |
| `PUT`    | `/api/v1/merchants/me/campaigns/{id}`                  | Update campaign           |
| `POST`   | `/api/v1/merchants/me/campaigns/{id}/publish`          | Publish campaign          |
| `POST`   | `/api/v1/merchants/me/campaigns/{id}/cancel`           | Cancel campaign           |
| `GET`    | `/api/v1/merchants/me/campaigns/{id}/analytics`        | Campaign analytics        |
| `GET`    | `/api/v1/merchants/me/campaigns/recurring`             | List recurring campaigns  |
| `POST`   | `/api/v1/merchants/me/campaigns/recurring`             | Create recurring campaign |
| `PATCH`  | `/api/v1/merchants/me/campaigns/recurring/{id}/toggle` | Toggle recurring campaign |
| `DELETE` | `/api/v1/merchants/me/campaigns/recurring/{id}`        | Delete recurring campaign |
| `GET`    | `/api/v1/merchants/me/notifications/summary`           | Notification summary      |

### Merchant Analytics

| Method | Path                                      | Description                 |
| ------ | ----------------------------------------- | --------------------------- |
| `GET`  | `/api/v1/merchants/me/analytics/overview` | Overview dashboard data     |
| `GET`  | `/api/v1/merchants/me/analytics/sessions` | Session analytics           |
| `GET`  | `/api/v1/merchants/me/analytics/revenue`  | Revenue analytics           |
| `GET`  | `/api/v1/merchants/me/analytics/funnel`   | Conversion funnel           |
| `GET`  | `/api/v1/merchants/me/analytics/push`     | Push notification analytics |
| `GET`  | `/api/v1/merchants/me/analytics/stories`  | Stories analytics           |
| `GET`  | `/api/v1/merchants/me/analytics/devices`  | Device analytics            |
| `GET`  | `/api/v1/merchants/me/analytics/loyalty`  | Loyalty analytics           |
| `GET`  | `/api/v1/merchants/me/analytics/realtime` | Real-time analytics         |
| `GET`  | `/api/v1/merchants/me/analytics/export`   | Export analytics CSV        |

### Merchant Abandoned Cart

| Method  | Path                                                | Description                  |
| ------- | --------------------------------------------------- | ---------------------------- |
| `GET`   | `/api/v1/merchants/me/abandoned-cart/config`        | Get abandoned cart config    |
| `PUT`   | `/api/v1/merchants/me/abandoned-cart/config`        | Update abandoned cart config |
| `PATCH` | `/api/v1/merchants/me/abandoned-cart/config/toggle` | Toggle abandoned cart        |
| `GET`   | `/api/v1/merchants/me/abandoned-cart/analytics`     | Abandoned cart analytics     |
| `GET`   | `/api/v1/merchants/me/abandoned-cart/carts`         | List abandoned carts         |

### Merchant Loyalty

| Method   | Path                                                         | Description            |
| -------- | ------------------------------------------------------------ | ---------------------- |
| `GET`    | `/api/v1/merchants/me/loyalty/config`                        | Get loyalty config     |
| `PUT`    | `/api/v1/merchants/me/loyalty/config`                        | Update loyalty config  |
| `GET`    | `/api/v1/merchants/me/loyalty/tiers`                         | List loyalty tiers     |
| `POST`   | `/api/v1/merchants/me/loyalty/tiers`                         | Create tier            |
| `PUT`    | `/api/v1/merchants/me/loyalty/tiers/{id}`                    | Update tier            |
| `DELETE` | `/api/v1/merchants/me/loyalty/tiers/{id}`                    | Delete tier            |
| `GET`    | `/api/v1/merchants/me/loyalty/customers`                     | List loyalty customers |
| `POST`   | `/api/v1/merchants/me/loyalty/customers/{customerId}/adjust` | Adjust customer points |
| `GET`    | `/api/v1/merchants/me/loyalty/analytics`                     | Loyalty analytics      |

### Merchant Reviews

| Method  | Path                                        | Description                     |
| ------- | ------------------------------------------- | ------------------------------- |
| `GET`   | `/api/v1/merchants/me/reviews`              | List all reviews (with filters) |
| `GET`   | `/api/v1/merchants/me/reviews/{id}`         | Get review detail               |
| `PATCH` | `/api/v1/merchants/me/reviews/{id}/approve` | Approve review                  |
| `PATCH` | `/api/v1/merchants/me/reviews/{id}/reject`  | Reject review                   |
| `POST`  | `/api/v1/merchants/me/reviews/{id}/reply`   | Reply to review                 |
| `GET`   | `/api/v1/merchants/me/reviews/analytics`    | Reviews analytics               |

### Merchant Segments

| Method   | Path                                          | Description            |
| -------- | --------------------------------------------- | ---------------------- |
| `GET`    | `/api/v1/merchants/me/segments`               | List customer segments |
| `POST`   | `/api/v1/merchants/me/segments`               | Create segment         |
| `GET`    | `/api/v1/merchants/me/segments/{id}/estimate` | Estimate segment size  |
| `PUT`    | `/api/v1/merchants/me/segments/{id}`          | Update segment         |
| `DELETE` | `/api/v1/merchants/me/segments/{id}`          | Delete segment         |

### Merchant Social Proof

| Method | Path                                       | Description                |
| ------ | ------------------------------------------ | -------------------------- |
| `GET`  | `/api/v1/merchants/me/social-proof/config` | Get social proof config    |
| `PUT`  | `/api/v1/merchants/me/social-proof/config` | Update social proof config |

### Merchant Stories

| Method   | Path                                                          | Description                |
| -------- | ------------------------------------------------------------- | -------------------------- |
| `GET`    | `/api/v1/merchants/me/story-groups`                           | List story groups          |
| `POST`   | `/api/v1/merchants/me/story-groups`                           | Create story group         |
| `PUT`    | `/api/v1/merchants/me/story-groups/{id}`                      | Update story group         |
| `DELETE` | `/api/v1/merchants/me/story-groups/{id}`                      | Delete story group         |
| `PATCH`  | `/api/v1/merchants/me/story-groups/reorder`                   | Reorder story groups       |
| `GET`    | `/api/v1/merchants/me/story-groups/{groupId}/stories`         | List stories in group      |
| `POST`   | `/api/v1/merchants/me/story-groups/{groupId}/stories`         | Create story               |
| `PUT`    | `/api/v1/merchants/me/story-groups/{groupId}/stories/{id}`    | Update story               |
| `DELETE` | `/api/v1/merchants/me/story-groups/{groupId}/stories/{id}`    | Delete story               |
| `PATCH`  | `/api/v1/merchants/me/story-groups/{groupId}/stories/reorder` | Reorder stories            |
| `GET`    | `/api/v1/merchants/me/story-groups/{id}/analytics`            | Story group analytics      |
| `GET`    | `/api/v1/merchants/me/stories/{id}/analytics`                 | Individual story analytics |
| `GET`    | `/api/v1/merchants/me/stories/summary`                        | Stories summary            |

### Merchant Integrations

| Method   | Path                                                  | Description                 |
| -------- | ----------------------------------------------------- | --------------------------- |
| `GET`    | `/api/v1/merchants/me/integrations`                   | List available integrations |
| `GET`    | `/api/v1/merchants/me/integrations/{slug}`            | Get integration detail      |
| `POST`   | `/api/v1/merchants/me/integrations/{slug}/connect`    | Connect integration         |
| `GET`    | `/api/v1/merchants/me/integrations/{slug}/status`     | Check integration status    |
| `POST`   | `/api/v1/merchants/me/integrations/{slug}/sync`       | Trigger manual sync         |
| `DELETE` | `/api/v1/merchants/me/integrations/{slug}/disconnect` | Disconnect integration      |

### Developer Auth

| Method | Path                            | Description                          |
| ------ | ------------------------------- | ------------------------------------ |
| `POST` | `/api/v1/auth/register/request` | Request OTP for registration         |
| `POST` | `/api/v1/auth/register/verify`  | Verify OTP and complete registration |
| `POST` | `/api/v1/auth/login/request`    | Request OTP for login                |
| `POST` | `/api/v1/auth/login/verify`     | Verify OTP and receive JWT           |
| `POST` | `/api/v1/auth/logout`           | Invalidate session                   |
| `POST` | `/api/v1/auth/refresh`          | Refresh JWT token                    |

### Developer Profile & API Keys

| Method   | Path                                        | Description              |
| -------- | ------------------------------------------- | ------------------------ |
| `GET`    | `/api/v1/developers/me`                     | Get developer profile    |
| `PATCH`  | `/api/v1/developers/me`                     | Update developer profile |
| `GET`    | `/api/v1/developers/me/plan`                | Get current plan         |
| `GET`    | `/api/v1/developers/me/slots`               | Get merchant slot usage  |
| `GET`    | `/api/v1/developers/me/api-keys`            | List API keys            |
| `POST`   | `/api/v1/developers/me/api-keys`            | Create API key           |
| `DELETE` | `/api/v1/developers/me/api-keys/{id}`       | Revoke API key           |
| `GET`    | `/api/v1/developers/me/api-keys/{id}/usage` | Get API key usage stats  |

### Developer Analytics

| Method | Path                                        | Description                  |
| ------ | ------------------------------------------- | ---------------------------- |
| `GET`  | `/api/v1/developers/me/analytics/overview`  | Developer overview analytics |
| `GET`  | `/api/v1/developers/me/analytics/merchants` | Per-merchant analytics       |
| `GET`  | `/api/v1/developers/me/analytics/usage`     | API usage analytics          |

### Developer Billing

| Method | Path                                 | Description             |
| ------ | ------------------------------------ | ----------------------- |
| `GET`  | `/api/v1/developer/plans`            | List developer plans    |
| `GET`  | `/api/v1/developer/billing/status`   | Get billing status      |
| `POST` | `/api/v1/developer/billing/checkout` | Create checkout session |

### Webhooks (Shopify → Stackfront)

| Method | Path                         | Description                |
| ------ | ---------------------------- | -------------------------- |
| `POST` | `/webhooks/{*topic}`         | Shopify webhook receiver   |
| `POST` | `/api/v1/webhooks/onesignal` | OneSignal delivery webhook |
| `POST` | `/webhooks/stripe`           | Stripe billing webhook     |