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:

{
  "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 (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

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/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

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

​API Reference

​Base URL

​Authentication

​SDK Endpoints (mobile app → Stackfront API)

​Merchant Endpoints (Shopify admin → Stackfront API)

​Developer Endpoints (developer dashboard → Stackfront API)

​Content-Type

​Errors

​Rate Limits

​Pagination

​Endpoints

​SDK Configuration

​SDK Push Notifications

​SDK Events & Analytics

​SDK Loyalty

​SDK Reviews

​SDK Social Proof

​SDK Stories

​SDK Integrations

​Merchant Auth

​Merchant Status & Setup

​Merchant Billing

​Merchant Branding & Content

​Merchant Campaigns & Push

​Merchant Analytics

​Merchant Abandoned Cart

​Merchant Loyalty

​Merchant Reviews

​Merchant Segments

​Merchant Social Proof

​Merchant Stories

​Merchant Integrations

​Developer Auth

​Developer Profile & API Keys

​Developer Analytics

​Developer Billing

​Webhooks (Shopify → Stackfront)