Get Plans (v1) - Client

Get all available subscription plans for client workspace selection.

Method & Path

GET /v1/client/plans

Description

Retrieves all active subscription plans available for workspace subscription. Plans are returned with localized names and descriptions based on the requested locale. This endpoint is used by the client system for plan selection during subscription setup or renewal.

Authentication

Not Required: This is a public endpoint accessible without authentication.

Query Parameters

Parameter	Type	Required	Description
locale	string	No	Locale code for localized plan names (e.g., "en", "ar"). Defaults to "en" if not provided or invalid.

Response 200 OK

{
  "locale": "en",
  "plans": [
    {
      "id": "507f1f77bcf86cd799439011",
      "slug": "basic-plan",
      "name": "Basic Plan",
      "description": "Basic plan for small businesses",
      "trialPeriodDays": 14,
      "sortOrder": 1,
      "pricePeriods": [
        {
          "period": "monthly",
          "amountCents": 2999,
          "currencyCode": "USD"
        },
        {
          "period": "quarterly",
          "amountCents": 8100,
          "currencyCode": "USD"
        },
        {
          "period": "semiannual",
          "amountCents": 16200,
          "currencyCode": "USD"
        },
        {
          "period": "annual",
          "amountCents": 29990,
          "currencyCode": "USD"
        }
      ],
      "features": [
        {
          "key": "unlimited-clients",
          "label": "Unlimited Clients",
          "description": "Add as many clients as you need"
        },
        {
          "key": "basic-support",
          "label": "Basic Support",
          "description": "Email support during business hours"
        }
      ],
      "flags": {
        "max-staff": "2",
        "max-storage": "5GB"
      },
      "assets": {
        "logo": {
          "url": "https://example.com/logo.png",
          "path": "/assets/plans/basic/logo.png",
          "width": 200,
          "height": 200,
          "sizeBytes": 15234,
          "contentType": "image/png"
        },
        "banner": {
          "url": "https://example.com/banner.png",
          "path": "/assets/plans/basic/banner.png",
          "width": 1200,
          "height": 400,
          "sizeBytes": 89234,
          "contentType": "image/png"
        }
      }
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "slug": "pro-plan",
      "name": "Pro Plan",
      "description": "Professional plan with advanced features",
      "trialPeriodDays": 14,
      "sortOrder": 2,
      "pricePeriods": [
        {
          "period": "monthly",
          "amountCents": 9900,
          "currencyCode": "USD"
        },
        {
          "period": "quarterly",
          "amountCents": 27000,
          "currencyCode": "USD"
        },
        {
          "period": "semiannual",
          "amountCents": 54000,
          "currencyCode": "USD"
        },
        {
          "period": "annual",
          "amountCents": 99000,
          "currencyCode": "USD"
        }
      ],
      "features": [
        {
          "key": "unlimited-clients",
          "label": "Unlimited Clients",
          "description": "Add as many clients as you need"
        },
        {
          "key": "priority-support",
          "label": "Priority Support",
          "description": "24/7 priority email and phone support"
        }
      ],
      "flags": {
        "max-staff": "50",
        "max-storage": "100GB"
      },
      "assets": {
        "logo": null,
        "banner": null
      }
    }
  ]
}

Response Fields

Field	Type	Description
locale	string	The locale used for localization (normalized from query parameter)
plans	array	Array of active subscription plans, sorted by sortOrder
plans[].id	string	Plan unique identifier
plans[].slug	string	Plan unique slug identifier
plans[].name	string	Localized plan name
plans[].description	string|null	Localized plan description
plans[].trialPeriodDays	number|null	Trial period in days (null if no trial)
plans[].sortOrder	number	Sort order for display
plans[].pricePeriods	array	Array of available billing periods with pricing
plans[].pricePeriods[].period	string	Billing period: "monthly", "quarterly", "semiannual", or "annual"
plans[].pricePeriods[].amountCents	number	Price in cents for this period
plans[].pricePeriods[].currencyCode	string	ISO 4217 currency code (e.g., "USD", "ILS", "JOD", "EUR")
plans[].features	array	Plan features with localized labels and descriptions
plans[].features[].key	string	Feature unique key
plans[].features[].label	string	Localized feature label
plans[].features[].description	string|null	Localized feature description
plans[].flags	object	Plan configuration flags as key-value pairs
plans[].assets	object	Plan visual assets (logo and banner images)
plans[].assets.logo	object|null	Plan logo image details or null
plans[].assets.banner	object|null	Plan banner image details or null

Localization

• Plans are returned with names, descriptions, and feature labels localized to the requested locale
• If a translation is not available for the requested locale, the default (first) translation is used
• Supported locales: "en", "ar" (and others as configured)
• If an invalid locale is provided, defaults to "en"

Plan Filtering

• Only active plans (isActive: true) are returned
• Plans are sorted by sortOrder (ascending), then by creation date

Price Periods

Each plan can have multiple price periods:

• Monthly: 30-day billing cycle
• Quarterly: 90-day (3-month) billing cycle
• Semiannual: 180-day (6-month) billing cycle
• Annual: 365-day (1-year) billing cycle

All price periods for a plan use the same currency code.

Example Usage

Get plans in English

curl -X GET "https://api.example.com/v1/client/plans?locale=en"

Get plans in Arabic

curl -X GET "https://api.example.com/v1/client/plans?locale=ar"

Get plans (default locale)

curl -X GET "https://api.example.com/v1/client/plans"

Common Errors

• 400 Bad Request: Invalid query parameters
• 500 Internal Server Error: Server error

Related Endpoints

• POST /v1/workspace/:workspaceId/subscription/renew - Renew subscription with selected plan and period
• GET /v1/admin/plans - Admin endpoint to manage plans (requires authentication)