Start a real subscription through the payment platform
POST/panel/workspaces/:workspace/subscription/new
Starts a real subscription for the workspace through the instance's active payment platform. Unlike POST /panel/workspaces/{workspace}/subscription, which only records an existing subscription, this endpoint contacts the payment platform and normally returns a checkout payload.
An active payment platform is required; without one the request fails.
Behaviour:
- If the workspace already has a recurring subscription, the request fails with 422.
- Generic-trial short-circuit — if generic trials are enabled with a trial length greater than zero, and the workspace has neither a generic subscription nor any other subscription, a generic subscription is created instead of a checkout and the request returns 409. Handle this as a success case, not an error.
- If the selected plan has no platform plan id for the requested billing cycle, the request fails with 422.
- Otherwise a checkout is created (return/cancel URLs, currency, trial days and an optional coupon) and the payment platform's response is returned unchanged.
Because step 4's body comes straight from the payment platform, its shape depends on which platform your instance uses and is not documented here.
Request
Responses
- 200
- 401
- 403
- 404
- 409
- 422
The payment platform's response, passed through unchanged (typically a checkout payload). Its shape depends on the active payment platform.
The bearer token is missing, malformed, unknown, or expired.
The token is valid, but the user it belongs to may not perform this action:
- they are not a member of the
{workspace}in the path; or - their workspace role is too low for this endpoint (write routes require Admin or Member); or
- for
/panelendpoints, they are not a platform administrator.
The host application that Mixpost is installed into can also deny access to Mixpost as a whole, which produces the same response.
The {workspace} UUID in the path does not match any workspace.
A generic trial subscription was created instead of a checkout. {"errors": {"created_generic_subscription": ["Your subscription has been created."]}}
Validation failed. Known messages:
subscription: "You can't subscribe to a plan while you have an active subscription."subscription: "You already subscribed." (returned by a second check for an existing recurring subscription)plan_id: "Platform plan not found"