Skip to main content

Regular Subscriptions

Manage regular subscriptions for features like EmotionalMap and Challenges. These subscriptions allow users to access specific features and set notification preferences.

Get Subscriptions​

Retrieve user's subscriptions by type.

Endpoint​

  • Method: GET
  • URL: /api/subscriptions

Request Headers​

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes
AuthorizationBearer YOUR_API_TOKENYes

Query Parameters​

ParameterTypeRequiredDescription
typestringYesMust be either 'EmotionalMap' or 'Challenge'
challenge_idintegerNoFilter subscriptions by specific challenge ID

Validation Rules​

FieldRules
typerequired, must be one of: 'EmotionalMap', 'Challenge'

Success Response​

{
"success": true,
"message": "Data retrieved successfully",
"data": [
{
"id": 1,
"subscribable_type": "EmotionalMap",
"subscribable_id": 1,
"created_at": "13/02/2025",
"status": "active"
}
]
}

Error Responses​

Validation Error​

{
"success": false,
"message": "error",
"data": "The type field is required",
"status": "validation-error"
}

Example validation errors:

  • "The type field is required"
  • "The type must be one of: EmotionalMap, Challenge"

Unauthorized​

{
"success": false,
"message": "Unauthenticated.",
"data": null,
"status_code": 401
}

Additional Notes​

  • If the user has a VIP subscription and paused regular subscriptions, the paused subscriptions will be automatically activated
  • The response is wrapped in SubscriptionsResource which formats the data consistently

Create Subscription​

Create a new subscription for a specific feature.

Endpoint​

  • Method: POST
  • URL: /api/subscribe

Request Headers​

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes
AuthorizationBearer YOUR_API_TOKENYes

Request Parameters​

ParameterTypeRequiredDescription
subscribable_idintegerYesID of the feature to subscribe to
subscribable_typestringYesMust be either 'EmotionalMap' or 'Challenge'
notification_timesarrayYesArray of notification settings
notification_times.*.togglestringYesMust be exactly 'true' or 'false'
notification_times.*.timestringYesTime for notification in HH:mm format

Request Body Example​

{
"subscribable_id": 1,
"subscribable_type": "EmotionalMap",
"notification_times": [
{
"toggle": "true",
"time": "09:00"
},
{
"toggle": "false",
"time": "18:00"
}
]
}

Validation Rules​

FieldRules
subscribable_idrequired
subscribable_typerequired, must be one of: 'EmotionalMap', 'Challenge'
notification_timesrequired, must be an array
notification_times.*must be an array with exactly 2 elements
notification_times.*.togglemust be one of: 'true', 'false'
notification_times.*.timemust be in format HH:mm

Success Response​

{
"success": true,
"message": "Subscription created successfully",
"data": {
"subscription_id": 1
}
}

Error Responses​

Validation Error​

{
"success": false,
"message": "error",
"data": "The subscribable type field is required",
"status": "validation-error"
}

Example validation errors:

  • "The subscribable id field is required"
  • "The subscribable type must be one of: EmotionalMap, Challenge"
  • "The notification times field is required"
  • "The notification times must be an array"
  • "The notification times.*.toggle must be one of: true, false"

Already Subscribed​

{
"success": false,
"message": "You are already subscribed to this feature",
"data": null
}

Unauthorized​

{
"success": false,
"message": "Unauthenticated.",
"data": null,
"status_code": 401
}

Implementation Details​

When creating a new subscription, the following default values are set:

  • status: Set to "active"
  • start_date: Set to current timestamp
  • is_active: Set to true
  • has_done_daily_action: Set to false
  • day: Set to 1
  • user_id: Set to authenticated user's ID
  • notification_times: Set to the provided notification times array

Update Notification Times​

Update notification preferences for an existing subscription.

Endpoint​

  • Method: POST
  • URL: /api/update-notification-times

Request Headers​

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes
AuthorizationBearer YOUR_API_TOKENYes

Request Parameters​

ParameterTypeRequiredDescription
subscription_idintegerYesID of the subscription to update
notification_timesarrayNoArray of notification settings
notification_times.*.togglestringYes (if notification_times provided)Must be exactly 'true' or 'false'
notification_times.*.timestringYes (if notification_times provided)Time for notification in HH:mm format

Request Body Example​

{
"subscription_id": 1,
"notification_times": [
{
"toggle": "true",
"time": "09:00"
},
{
"toggle": "false",
"time": "18:00"
}
]
}

Note: When notification_times is provided, each element must contain exactly 2 elements (toggle and time).

Validation Rules​

FieldRules
subscription_idrequired
notification_times.*must be an array with exactly 2 elements
notification_times.*.togglemust be one of: 'true', 'false'
notification_times.*.timemust be in format HH:mm

Success Response​

{
"success": true,
"message": "Data updated successfully",
"data": null
}

Error Responses​

Validation Error​

{
"success": false,
"message": "error",
"data": "The subscription id field is required",
"status": "validation-error"
}

Example validation errors:

  • "The subscription id field is required"
  • "The notification times.*.toggle must be one of: true, false"

Subscription Not Found​

{
"success": false,
"message": "Subscription not found",
"data": null
}

Unauthorized​

{
"success": false,
"message": "Unauthenticated.",
"data": null,
"status_code": 401
}

Example Implementation Flow​

  1. User modifies notification preferences
  2. System validates the new notification times
  3. System updates the subscription record
  4. System returns the updated notification settings