REST API

SubX REST API endpoint reference. All requests are JSON format and require authentication.

Authentication

Two authentication methods are supported:

Method	Header	Usage
JWT 토큰	`Authorization: Bearer <token>`	Dashboard logged-in users
API 키	`X-API-Key: your_api_key`	Server-side / SDK / MCP integration

Base URL

https://api.subx.dev

Authentication

Method	Path	Description
POST	`/auth/register`	Register
POST	`/auth/login`	Login (issue JWT)
POST	`/auth/refresh`	Refresh JWT token
GET	`/auth/me`	Get current user info

Projects

Method	Path	Description
GET	`/v1/projects`	List projects
POST	`/v1/projects`	Create project
GET	`/v1/projects/:id`	Get project details
PATCH	`/v1/projects/:id`	Update project
DELETE	`/v1/projects/:id`	Delete project
GET	`/v1/projects/:id/setup-status`	Get setup progress status

API Keys

Method	Path	Description
GET	`/v1/projects/:id/api-keys`	List API keys
POST	`/v1/projects/:id/api-keys`	Create API key (full key only shown immediately after creation)
DELETE	`/v1/projects/:id/api-keys/:keyId`	Delete API key

Apps

Method	Path	Description
GET	`/v1/projects/:id/apps`	List apps
POST	`/v1/projects/:id/apps`	Register app (iOS/Android)
GET	`/v1/projects/:id/apps/:appId`	Get app details
PATCH	`/v1/projects/:id/apps/:appId`	Update app settings
DELETE	`/v1/projects/:id/apps/:appId`	Delete app
POST	`/v1/projects/:id/apps/:appId/credentials/apple`	Register Apple credentials
POST	`/v1/projects/:id/apps/:appId/credentials/google`	Register Google credentials
GET	`/v1/projects/:id/apps/:appId/credentials/status`	Get credentials and notification status
DELETE	`/v1/projects/:id/apps/:appId/credentials`	Delete credentials

App Settings

The following settings can be changed via PATCH /v1/projects/:id/apps/:appId:

Field	Type	Description
`notificationForwardingUrl`	`string \| null`	Forwards Apple/Google store notifications to this URL as well
`refundPolicy`	`enum`	revoke_immediately (default) or keep_until_expiry
`appleSmallBusiness`	`boolean`	Apple Small Business Program (15% commission)

Products

Method	Path	Description
GET	`/v1/projects/:id/products`	List products
POST	`/v1/projects/:id/products`	Create product
GET	`/v1/projects/:id/products/:pid`	Get product details
DELETE	`/v1/projects/:id/products/:pid`	Delete product
POST	`/v1/projects/:id/products/:pid/prices`	Add price
DELETE	`/v1/projects/:id/products/:pid/prices/:priceId`	Delete price

Entitlements

Method	Path	Description
GET	`/v1/projects/:id/entitlements`	List entitlements
POST	`/v1/projects/:id/entitlements`	Create entitlement
GET	`/v1/projects/:id/entitlements/:eid`	Get entitlement details
PATCH	`/v1/projects/:id/entitlements/:eid`	Update entitlement
DELETE	`/v1/projects/:id/entitlements/:eid`	Delete entitlement
GET	`/v1/projects/:id/entitlements/:eid/products`	List attached products
POST	`/v1/projects/:id/entitlements/:eid/products`	Attach product
DELETE	`/v1/projects/:id/entitlements/:eid/products`	Detach product

Offerings

Method	Path	Description
GET	`/v1/projects/:id/offerings`	List offerings
POST	`/v1/projects/:id/offerings`	Create offering
PATCH	`/v1/projects/:id/offerings/:oid`	Update offering
GET	`/v1/projects/:id/offerings/:oid/packages`	List packages
POST	`/v1/projects/:id/offerings/:oid/packages`	Create package
DELETE	`/v1/projects/:id/offerings/:oid/packages/:pid`	Delete package
POST	`/v1/projects/:id/offerings/:oid/packages/:pid/products`	Attach product to package
DELETE	`/v1/projects/:id/offerings/:oid/packages/:pid/products`	Detach product from package

Paywalls

Method	Path	Description
GET	`/v1/projects/:id/paywalls`	List paywalls
POST	`/v1/projects/:id/paywalls`	Create paywall
GET	`/v1/projects/:id/paywalls/:pwid`	Get paywall details
PATCH	`/v1/projects/:id/paywalls/:pwid`	Update paywall
DELETE	`/v1/projects/:id/paywalls/:pwid`	Delete paywall

Customers

Method	Path	Description
GET	`/v1/projects/:id/customers`	List customers (search, pagination)
GET	`/v1/projects/:id/customers/:cid`	Get customer details (including subscriptions, entitlements)

Webhooks

Method	Path	Description
GET	`/v1/projects/:id/webhooks`	List webhooks
POST	`/v1/projects/:id/webhooks`	Create webhook
GET	`/v1/projects/:id/webhooks/:wid`	Get webhook details
PATCH	`/v1/projects/:id/webhooks/:wid`	Update webhook
DELETE	`/v1/projects/:id/webhooks/:wid`	Delete webhook

Experiments (A/B Testing)

Method	Path	Description
GET	`/v1/projects/:id/experiments`	List experiments
POST	`/v1/projects/:id/experiments`	Create experiment
GET	`/v1/projects/:id/experiments/:eid`	Get experiment details
PATCH	`/v1/projects/:id/experiments/:eid`	Update experiment
DELETE	`/v1/projects/:id/experiments/:eid`	Delete experiment
POST	`/v1/projects/:id/experiments/:eid/variants`	Add variant
DELETE	`/v1/projects/:id/experiments/:eid/variants/:vid`	Delete variant

Metrics & Charts

Method	Path	Description
GET	`/v1/projects/:id/metrics/overview`	Dashboard overview metrics
GET	`/v1/projects/:id/metrics/charts`	Available chart types (21 types)
GET	`/v1/projects/:id/metrics/charts/:chartId`	Get chart data (specify period and interval)

Subscribers (SDK)

Method	Path	Description
GET	`/v1/subscribers/:appUserId`	Get subscriber info
POST	`/v1/subscribers/:appUserId`	Create/update subscriber
POST	`/v1/subscribers/:appUserId/attributes`	Set custom attributes
POST	`/v1/subscribers/:appUserId/entitlements`	Grant promotional entitlement
DELETE	`/v1/subscribers/:appUserId/entitlements/:eid`	Revoke promotional entitlement
POST	`/v1/subscribers/:appUserId/receipts`	Submit store receipt

SDK Offerings

Method	Path	Description
GET	`/v1/offerings`	Get current offering (API key auth)
GET	`/v1/offerings/:oid/paywalls`	Get offering paywalls
GET	`/v1/subscribers/:appUserId/offerings`	Get offerings by subscriber
POST	`/v1/events`	Record custom event

Store Notifications

Method	Path	Description
POST	`/v1/store/apple/:token`	Apple S2S notification endpoint
POST	`/v1/store/google/:token`	Google S2S notification endpoint

Request Examples

Create Product

POST https://api.subx.dev/v1/projects/:projectId/products
Content-Type: application/json
X-API-Key: your_api_key

{
  "appId": "app_xyz789",
  "storeProductId": "com.example.pro.monthly",
  "displayName": "Pro Monthly",
  "type": "subscription"
}

Update App Settings

PATCH https://api.subx.dev/v1/projects/:projectId/apps/:appId
Content-Type: application/json
X-API-Key: your_api_key

{
  "notificationForwardingUrl": "https:1
  6: "keep_until_expiry",
  "appleSmallBusiness": true
}

Error Responses

All errors are returned in the following format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Status Code	Description
`400`	Bad Request (missing required fields, validation failure)
`401`	Unauthorized (missing or expired token/API key)
`403`	Forbidden
`404`	Resource not found
`500`	Internal Server Error

Next Steps

Webhooks — 서버에서 구독 이벤트를 수신합니다.
SDK Integration — iOS/Android 앱에 SubX SDK를 연동합니다.
Store Setup — App Store Connect / Google Play Console 설정 방법을 확인합니다.