Subscriptions API

Manage seller subscription plans and billing via the API.

Endpoints Overview

Method	Endpoint	Description	Auth
GET	`/api/subscriptions/plans`	List available plans	No
GET	`/api/subscriptions/current`	Get current subscription	Required
POST	`/api/subscriptions/subscribe`	Create Stripe checkout	Required
POST	`/api/subscriptions/change-plan`	Switch to different plan	Required
POST	`/api/subscriptions/cancel`	Cancel subscription	Required
POST	`/api/subscriptions/billing-portal`	Access Stripe portal	Required

List Plans

Get available subscription plans.

Request

bash

GET /v1/subscriptions/plans
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "plan_free",
        "name": "Free",
        "description": "Basic features for getting started",
        "price": {
          "monthly": 0,
          "annual": 0,
          "currency": "USD"
        },
        "features": {
          "listings": 5,
          "photos_per_listing": 10,
          "team_members": 1,
          "featured_credits": 0,
          "bulk_upload": false,
          "api_access": false,
          "analytics": "basic"
        }
      },
      {
        "id": "plan_starter",
        "name": "Starter",
        "description": "For growing sellers",
        "price": {
          "monthly": 49,
          "annual": 470,
          "currency": "USD"
        },
        "features": {
          "listings": 25,
          "photos_per_listing": 20,
          "team_members": 2,
          "featured_credits": 2,
          "bulk_upload": false,
          "api_access": false,
          "analytics": "standard"
        }
      },
      {
        "id": "plan_professional",
        "name": "Professional",
        "description": "For established dealers",
        "price": {
          "monthly": 149,
          "annual": 1430,
          "currency": "USD"
        },
        "features": {
          "listings": 100,
          "photos_per_listing": 50,
          "team_members": 5,
          "featured_credits": 10,
          "bulk_upload": true,
          "api_access": true,
          "analytics": "advanced"
        }
      },
      {
        "id": "plan_enterprise",
        "name": "Enterprise",
        "description": "For large operations",
        "price": {
          "monthly": null,
          "annual": null,
          "currency": "USD",
          "custom": true
        },
        "features": {
          "listings": -1,
          "photos_per_listing": -1,
          "team_members": -1,
          "featured_credits": -1,
          "bulk_upload": true,
          "api_access": true,
          "analytics": "full"
        }
      }
    ]
  }
}

Get Current Subscription

Get the authenticated user's current subscription.

Request

bash

GET /v1/subscriptions/current
Authorization: Bearer YOUR_JWT_TOKEN

Response

json

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "plan": {
        "id": "plan_professional",
        "name": "Professional"
      },
      "status": "active",
      "billing_cycle": "monthly",
      "current_period": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      },
      "price": {
        "amount": 149,
        "currency": "USD"
      },
      "payment_method": {
        "type": "card",
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2025
      },
      "auto_renew": true,
      "created_at": "2023-06-15T10:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    "usage": {
      "listings": {
        "used": 45,
        "limit": 100,
        "percentage": 45
      },
      "team_members": {
        "used": 3,
        "limit": 5,
        "percentage": 60
      },
      "featured_credits": {
        "used": 7,
        "limit": 10,
        "remaining": 3
      }
    }
  }
}

Create Subscription

Subscribe to a plan.

Request

bash

POST /v1/subscriptions
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body

json

{
  "plan_id": "plan_professional",
  "billing_cycle": "monthly",
  "payment_method_id": "pm_card_abc123"
}

Response

json

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_new123",
      "plan": {
        "id": "plan_professional",
        "name": "Professional"
      },
      "status": "active",
      "billing_cycle": "monthly",
      "current_period": {
        "start": "2024-01-15T00:00:00Z",
        "end": "2024-02-14T23:59:59Z"
      },
      "created_at": "2024-01-15T10:00:00Z"
    }
  }
}

Update Subscription

Change plan or billing cycle.

Request

bash

PUT /v1/subscriptions
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body

json

{
  "plan_id": "plan_starter",
  "billing_cycle": "annual",
  "prorate": true
}

Response

json

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "plan": {
        "id": "plan_starter",
        "name": "Starter"
      },
      "status": "active",
      "billing_cycle": "annual",
      "effective_date": "2024-02-01T00:00:00Z",
      "proration": {
        "credit": 50.25,
        "charge": 470.00,
        "net": 419.75
      }
    }
  }
}

Cancel Subscription

Cancel the current subscription.

Request

bash

DELETE /v1/subscriptions
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body

json

{
  "reason": "no_longer_needed",
  "feedback": "Moving to a different platform",
  "cancel_immediately": false
}

Response

json

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "status": "canceled",
      "canceled_at": "2024-01-15T10:00:00Z",
      "access_until": "2024-01-31T23:59:59Z"
    }
  }
}

Reactivate Subscription

Reactivate a canceled subscription.

Request

bash

POST /v1/subscriptions/reactivate
Authorization: Bearer YOUR_JWT_TOKEN

List Invoices

Get subscription invoices.

Request

bash

GET /v1/subscriptions/invoices
Authorization: Bearer YOUR_JWT_TOKEN

Query Parameters

Parameter	Type	Description
`page`	integer	Page number
`limit`	integer	Items per page
`status`	string	paid, pending, failed

Response

json

{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": "inv_123",
        "number": "INV-2024-001",
        "date": "2024-01-01",
        "due_date": "2024-01-01",
        "status": "paid",
        "items": [
          {
            "description": "Professional Plan - Monthly",
            "amount": 149.00
          }
        ],
        "subtotal": 149.00,
        "tax": 0,
        "total": 149.00,
        "currency": "USD",
        "paid_at": "2024-01-01T00:00:05Z",
        "pdf_url": "https://api.menonmobility.com/v1/invoices/inv_123/pdf"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 12
    }
  }
}

Get Invoice

Get a specific invoice.

Request

bash

GET /v1/subscriptions/invoices/inv_123
Authorization: Bearer YOUR_JWT_TOKEN

Download PDF

bash

GET /v1/subscriptions/invoices/inv_123/pdf
Authorization: Bearer YOUR_JWT_TOKEN

Get Usage

Get current usage statistics.

Request

bash

GET /v1/subscriptions/usage
Authorization: Bearer YOUR_JWT_TOKEN

Response

json

{
  "success": true,
  "data": {
    "usage": {
      "listings": {
        "used": 45,
        "limit": 100,
        "percentage": 45
      },
      "photos": {
        "used": 890,
        "limit": 5000,
        "percentage": 17.8
      },
      "team_members": {
        "used": 3,
        "limit": 5,
        "percentage": 60
      },
      "featured_credits": {
        "used": 7,
        "limit": 10,
        "remaining": 3,
        "resets_at": "2024-02-01T00:00:00Z"
      },
      "api_calls": {
        "used": 4500,
        "limit": 10000,
        "percentage": 45,
        "resets_at": "2024-02-01T00:00:00Z"
      }
    }
  }
}

Payment Methods

List Payment Methods

bash

GET /v1/subscriptions/payment-methods
Authorization: Bearer YOUR_JWT_TOKEN

Add Payment Method

bash

POST /v1/subscriptions/payment-methods
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "type": "card",
  "token": "tok_visa_abc123"
}

Set Default Payment Method

bash

PUT /v1/subscriptions/payment-methods/pm_123/default
Authorization: Bearer YOUR_JWT_TOKEN

Remove Payment Method

bash

DELETE /v1/subscriptions/payment-methods/pm_123
Authorization: Bearer YOUR_JWT_TOKEN

Webhooks

Subscribe to subscription events:

subscription.created
subscription.updated
subscription.canceled
subscription.renewed
invoice.paid
invoice.failed
payment.failed

See Webhooks for details.

Subscriptions API ​

Endpoints Overview ​

List Plans ​

Request ​

Response ​

Get Current Subscription ​

Request ​

Response ​

Create Subscription ​

Request ​

Body ​

Response ​

Update Subscription ​

Request ​

Body ​

Response ​

Cancel Subscription ​

Request ​

Body ​

Response ​

Reactivate Subscription ​

Request ​

List Invoices ​

Request ​

Query Parameters ​

Response ​

Get Invoice ​

Request ​

Download PDF ​

Get Usage ​

Request ​

Response ​

Payment Methods ​

List Payment Methods ​

Add Payment Method ​

Set Default Payment Method ​

Remove Payment Method ​

Webhooks ​

Related Topics ​

Subscriptions API

Endpoints Overview

List Plans

Request

Response

Get Current Subscription

Request

Response

Create Subscription

Request

Body

Response

Update Subscription

Request

Body

Response

Cancel Subscription

Request

Body

Response

Reactivate Subscription

Request

List Invoices

Request

Query Parameters

Response

Get Invoice

Request

Download PDF

Get Usage

Request

Response

Payment Methods

List Payment Methods

Add Payment Method

Set Default Payment Method

Remove Payment Method

Webhooks

Related Topics