Renew Subscription (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/subscription/renew

Actual backend path: /v1/workspace/:workspaceId/subscription/renew

Description

Renew the workspace subscription. When payment method is card, the request is charged via the configured card payment provider (e.g. Cherry Tech / Cybersource). On success, the subscription end date is extended and a payment record is created with a description indicating which provider account the payment was settled to. When payment method is whatsapp, a payment record may be created but the subscription is not extended automatically; the admin extends it after manual payment. Card data is never stored; there is no auto-renewal.

Authentication

Required: Workspace owner JWT (Bearer token). The authenticated user must be the owner of the workspace.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <workspace_owner_jwt>
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID (MongoDB ObjectId)

Query Parameters

None.

Request Body

{
  "paymentMethod": "card",
  "period": "monthly",
  "planId": "507f1f77bcf86cd799439011",
  "cardDetails": {
    "cardNumber": "4111111111111111",
    "expiryDate": "12/28",
    "cvv": "123",
    "cardholderName": "John Doe"
  }
}

Field	Type	Required	Description
paymentMethod	string	Yes	"whatsapp" or "card"
period	string	No	"monthly" | "quarterly" | "semiannual" | "annual". Default: "monthly"
planId	string	No	Plan ID; defaults to workspace's current plan
cardDetails	object	Required when paymentMethod is "card"	Card data (not stored).
cardDetails.cardNumber	string	Yes (if card)	Card number (digits only or with spaces)
cardDetails.expiryDate	string	Yes (if card)	Expiry in MM/YY or MM/YYYY format
cardDetails.cvv	string	Yes (if card)	Card security code
cardDetails.cardholderName	string	Yes (if card)	Name on card

Response 200 OK

{
  "success": true,
  "newSubscriptionEndDate": "2025-03-15T00:00:00.000Z",
  "message": "Subscription renewed successfully."
}

When paymentMethod is "whatsapp":

{
  "success": true,
  "message": "Please contact us via WhatsApp to complete your subscription renewal."
}

(newSubscriptionEndDate is omitted for WhatsApp as the subscription is extended manually by admin.)

Common Errors

• 400 Bad Request: Invalid workspace ID; card payment enabled but card details missing or invalid; card payment not enabled or no provider configured; payment declined or failed at provider.
• 401 Unauthorized: Missing or invalid token.
• 403 Forbidden: Authenticated user is not the workspace owner.
• 404 Not Found: Workspace or plan not found.
• 422 Unprocessable Entity: Validation error (e.g. card details required when payment method is card).

Notes

• Card data is never stored. It is sent to the payment provider (e.g. Cybersource) and discarded.
• Each successful card payment is stored as a PaymentTransaction (provider response, no card data) and linked to an AdminPayment with a description that the payment was settled to the configured provider account (e.g. "الدفعة نزلت بحساب البروفايدر شيري تيك").
• Platform settings control whether card payment is enabled and which provider is used (e.g. Cherry Tech). Configure via Admin panel Settings → طرق الدفع → بروفايدر الدفع بالبطاقة.