StartFragment
\nThis API provides a complete subscription lifecycle management system that simulates real-world SaaS behavior.
\nIt handles all stages of a subscription:
\nFree trials
\nPayments
\nFailed payments & retries
\nGrace periods
\nCancellation
\nAutomated lifecycle transitions
\nThe system is built using Laravel with a clean architecture approach.
\nThe project follows a Service + Repository Pattern:
\nController โ Handles HTTP requests/responses
\nService Layer โ Contains business logic
\nRepository Layer โ Handles database operations
\nPolicy Layer โ Manages authorization
\nEnums โ Manages subscription states
\nLaravel
\nLaravel Sanctum (Authentication)
\nMySQL
\nPostman (API Testing & Documentation)
\nAll protected endpoints require:
\nAuthorization: Bearer {token}\n\nResponsible for managing subscription plans.
\nPermissions:
\nCreate plans
\nUpdate plans
\nDelete plans
\nResponsible for interacting with subscriptions.
\nPermissions:
\nStart trial
\nPay subscription
\nRetry failed payments
\nCancel subscription
\nView own subscriptions only
\nUsers can only access their own subscriptions
\nPolicies are used to enforce ownership:
\nSubscriptionPolicyAdmin-only access for plan management
\nUnauthorized actions return 403 Forbidden
\ntrialing โ past_due โ canceled\n โ\n active โ canceled\n\nA user can have only one active or trial subscription
\nPayment is not allowed during trial
\nPayment success โ moves subscription to active
\nPayment failure โ moves subscription to past_due
\nGrace period lasts 3 days
\nRetry is only allowed when status = past_due
\nCanceled subscriptions cannot be modified
\nTrial expiration automatically moves to past_due
\nA scheduled command runs daily:
\nphp artisan subscriptions:check\n\nMove expired trials โ past_due
Move expired grace periods โ canceled
POST /api/subscriptions/start-trial\n\nBody:
\n{\n \"plan_id\": 1\n}\n\nPOST /api/subscriptions/{id}/pay\n\nBody:
\n{\n \"status\": \"success | failed\"\n}\n\nPOST /api/subscriptions/{id}/retry\n\nPOST /api/subscriptions/{id}/cancel\n\nGET /api/subscriptions\n\nTracks:
\nPayment amount
\nCurrency
\nPayment status (paid / failed)
\nPayment date
\nTracks all attempts:
\nattempt number
\nsuccess / failure
\ntimestamp
\nUsed for:
\nretry logic
\nanalytics
\ndebugging
\nUser starts trial โ trialing
Trial expires โ past_due
User retries payment:
\nsuccess โ active
failure โ stays past_due
Grace period ends โ canceled
Payments are simulated (no real gateway integration)
\nSystem designed to mimic real SaaS platforms like Stripe
\nEasily extendable to integrate real payment gateways
\nAhmed Abdulhamid
\nEndFragment
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"๐ Subscription Lifecycle API","slug":"subscription-lifecycle-api"}],"owner":"29985463","collectionId":"325860a2-674e-48d6-bc82-558e98cec23c","publishedId":"2sBXiqEp7J","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-04-06T07:19:15.000Z"},"item":[{"name":"users","item":[{"name":"create user","id":"7004a8c9-8cfb-4475-ac1c-be69824800af","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"name\":\"ahmed\",\r\n \"email\":\"ahmed@gmail.com\",\r\n \"role\":\"user\",\r\n \"password\":\"password\",\r\n \r\n \r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"{{supscriptions_url}}/register","urlObject":{"path":["register"],"host":["{{supscriptions_url}}"],"query":[],"variable":[]}},"response":[{"id":"6be17d06-6aa5-44f8-b20c-888264fc54e6","name":"create user","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"name\":\"ahmed\",\r\n \"email\":\"ahmed@gmail.com\",\r\n \"role\":\"user\",\r\n \"password\":\"password\",\r\n \"password_confirmation\":\"password\"\r\n \r\n \r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"{{supscriptions_url}}/register"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Mon, 06 Apr 2026 04:42:36 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"User registered successfully\",\n \"data\": {\n \"id\": 4,\n \"name\": \"ahmed\",\n \"email\": \"ahmed@gmail.com\",\n \"role\": \"user\",\n \"created_at\": \"2026-04-06 \"\n },\n \"code\": 201\n}"}],"_postman_id":"7004a8c9-8cfb-4475-ac1c-be69824800af"},{"name":"login user","id":"a5ac37a0-4ea6-4aa1-96ac-1d00b528ad25","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"StartFragment
\nCreates a new subscription plan.
\nEndFragment
\n","urlObject":{"path":["plans"],"host":["{{supscriptions_url}}"],"query":[],"variable":[]}},"response":[{"id":"a2b94d1c-2720-4ab2-be34-7f19c7f6c246","name":"storePlan","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"name\":\"plan2 name\",\r\n \"price\":500.00,\r\n \"currency_id\":2,\r\n \"interval\":\"yearly\",\r\n \"trial_days\":7,\r\n \"is_active\":1\r\n}","options":{"raw":{"language":"json"}}},"url":"{{supscriptions_url}}/plans"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 05 Apr 2026 07:53:42 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Plan created successfully\",\n \"data\": {\n \"id\": 7,\n \"name\": \"plan2 name\",\n \"price\": \"500.00\",\n \"currency_code\": \"EGP\",\n \"currency\": {\n \"id\": 2,\n \"code\": \"EGP\",\n \"name\": \"Egyptian Pound\"\n },\n \"interval\": \"yearly\",\n \"trial_days\": 7,\n \"is_active\": true\n },\n \"code\": 201\n}"}],"_postman_id":"471a1362-10bb-4a95-b7b3-21807e0e1845"},{"name":"updatePlan","id":"08bf30a6-18ef-4a1c-afb2-b44764617700","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"StartFragment
\nUpdate a subscription plan.
\nEndFragment
\n","urlObject":{"path":["plans","basic-monthly-yearly-2"],"host":["{{supscriptions_url}}"],"query":[],"variable":[]}},"response":[{"id":"c4c5564c-51f5-467c-acba-720c48534cb1","name":"updatePlan","originalRequest":{"method":"PUT","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"name\":\"hello world\",\r\n \"price\":500.00,\r\n \"currency_id\":2,\r\n \"interval\":\"yearly\",\r\n \"trial_days\":7,\r\n \"is_active\":1\r\n}","options":{"raw":{"language":"json"}}},"url":"{{supscriptions_url}}/plans/basic-monthly-yearly-2"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 05 Apr 2026 08:01:01 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Plan updated successfully\",\n \"data\": {\n \"id\": 1,\n \"name\": \"hello world\",\n \"price\": \"500.00\",\n \"currency_code\": \"EGP\",\n \"currency\": {\n \"id\": 2,\n \"code\": \"EGP\",\n \"name\": \"Egyptian Pound\"\n },\n \"interval\": \"yearly\",\n \"trial_days\": 7,\n \"is_active\": true\n },\n \"code\": 200\n}"}],"_postman_id":"08bf30a6-18ef-4a1c-afb2-b44764617700"},{"name":"DeletePlan","id":"51019e99-1580-4a04-9169-446b46cec93e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"StartFragment
\nDeletes a subscription plan.
\nEndFragment
\n","urlObject":{"path":["plans","plan2 name-yearly-2"],"host":["{{supscriptions_url}}"],"query":[],"variable":[]}},"response":[{"id":"cf2ee15a-6f41-4bb5-86e6-2062b6d957ee","name":"DeletePlan","originalRequest":{"method":"DELETE","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{supscriptions_url}}/plans/hello world-yearly-2"},"status":"OK","code":200,"_postman_previewlanguage":"","header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 05 Apr 2026 08:09:04 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Plan deleted successfully\",\n \"data\": null,\n \"code\": 200\n}"}],"_postman_id":"51019e99-1580-4a04-9169-446b46cec93e"}],"id":"183dd919-d8f2-493d-a74d-eda2a0e642de","_postman_id":"183dd919-d8f2-493d-a74d-eda2a0e642de","description":""},{"name":"subscriptions","item":[{"name":"getAllSubscriptions","id":"002a1b8c-6812-4b94-8df6-0d0c6268973f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"urlObject":{"query":[],"variable":[]},"url":""},"response":[{"id":"1f9ce698-3413-41fa-b268-e22e977da075","name":"getAllSubscriptions","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":""},"url":"{{supscriptions_url}}/subscriptions"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 05 Apr 2026 10:19:17 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Subscriptions retrieved successfully\",\n \"data\": [\n {\n \"id\": 1,\n \"user\": {\n \"id\": 2,\n \"name\": \"Test User\",\n \"email\": \"test@example.com\",\n \"role\": \"user\",\n \"created_at\": \"2026-04-05 \"\n },\n \"plan\": {\n \"id\": 1,\n \"name\": \"hello world\",\n \"price\": \"500.00\",\n \"currency_code\": \"EGP\",\n \"currency\": {\n \"id\": 2,\n \"code\": \"EGP\",\n \"name\": \"Egyptian Pound\"\n },\n \"interval\": \"yearly\",\n \"trial_days\": 7,\n \"is_active\": true\n },\n \"status\": \"active\",\n \"trial_ends_at\": null,\n \"current_period_start\": \"2026-04-05\",\n \"current_period_end\": \"2026-05-05\",\n \"grace_period_end\": null,\n \"canceled_at\": null,\n \"auto_renew\": true\n },\n {\n \"id\": 2,\n \"user\": {\n \"id\": 3,\n \"name\": \"Test User2\",\n \"email\": \"test2@example.com\",\n \"role\": \"user\",\n \"created_at\": \"2026-04-05 \"\n },\n \"plan\": {\n \"id\": 3,\n \"name\": \"Premium Yearly\",\n \"price\": \"499.99\",\n \"currency_code\": \"EGP\",\n \"currency\": {\n \"id\": 2,\n \"code\": \"EGP\",\n \"name\": \"Egyptian Pound\"\n },\n \"interval\": \"yearly\",\n \"trial_days\": 30,\n \"is_active\": true\n },\n \"status\": \"trialing\",\n \"trial_ends_at\": \"2026-0505\",\n \"current_period_start\": null,\n \"current_period_end\": null,\n \"grace_period_end\": null,\n \"canceled_at\": null,\n \"auto_renew\": true\n }\n ],\n \"code\": 200\n}"}],"_postman_id":"002a1b8c-6812-4b94-8df6-0d0c6268973f"},{"name":"show subscription","id":"821c8481-e703-47a4-a0c5-418206d63d17","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"urlObject":{"query":[],"variable":[]},"url":""},"response":[{"id":"231de8f9-be13-4ab2-95db-40cf546938f3","name":"show subscription","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"{{supscriptions_url}}/subscriptions/1"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Connection","value":"close"},{"key":"X-Powered-By","value":"PHP/8.2.12"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 05 Apr 2026 10:25:03 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"message\": \"Subscription retrieved successfully\",\n \"data\": {\n \"id\": 1,\n \"user\": {\n \"id\": 2,\n \"name\": \"Test User\",\n \"email\": \"test@example.com\",\n \"role\": \"user\",\n \"created_at\": \"2026-04-05 \"\n },\n \"plan\": {\n \"id\": 1,\n \"name\": \"hello world\",\n \"price\": \"500.00\",\n \"currency_code\": \"EGP\",\n \"currency\": {\n \"id\": 2,\n \"code\": \"EGP\",\n \"name\": \"Egyptian Pound\"\n },\n \"interval\": \"yearly\",\n \"trial_days\": 7,\n \"is_active\": true\n },\n \"status\": \"active\",\n \"trial_ends_at\": null,\n \"current_period_start\": \"2026-04-05\",\n \"current_period_end\": \"2026-05-05\",\n \"grace_period_end\": null,\n \"canceled_at\": null,\n \"auto_renew\": true\n },\n \"code\": 200\n}"}],"_postman_id":"821c8481-e703-47a4-a0c5-418206d63d17"},{"name":"startTrial","id":"1487de4a-2702-46dd-b159-caa9a9926595","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"