Business API Design Specification - Cancel Companysubscription

A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic.

While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized.

This document provides an in-depth explanation of the architectural design of the cancelCompanySubscription Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side.

Main Data Object and CRUD Operation

The cancelCompanySubscription Business API is designed to handle a update operation on the CompanySubscription data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow.

API Description

Cancels a company’s active subscription. Calls Stripe to cancel the subscription, then updates the local record to canceled status. Only tenantOwner/tenantAdmin of the owning company or superAdmin/saasAdmin can cancel.

API Frontend Description By The Backend Architect

Company admins use this to cancel their AI subscription. The Stripe subscription is canceled and the local record is updated. After cancellation, AI features are immediately blocked.

API Options

API Controllers

A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel.

REST Controller

The cancelCompanySubscription Business API includes a REST controller that can be triggered via the following route:

/v1/cancelcompanysubscription/:companySubscriptionId

By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the Parameters section.

MCP Tool

REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This cancelCompanySubscription Business API will be registered as a tool on the MCP server within the service binding.

API Parameters

The cancelCompanySubscription Business API has 9 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client.

Business API parameters can be:

Regular Parameters

Name Type Required Default Location Data Path
companySubscriptionId ID Yes - urlpath companySubscriptionId
Description: This id paremeter is used to select the required data object that will be updated
activationDate Date No - body activationDate
Description: Start date/time when subscription is (re)activated.
expiryDate Date No - body expiryDate
Description: Planned end date/time of subscription validity (inclusive).
status Enum No - body status
Description: Subscription status: active, inactive, pending, or expired.
subscribedFeatures String[] No - body subscribedFeatures
Description: Array of enabled feature flags for this company’s subscription (e.g., aiAnalytics, reporting, notifications). — Array parameter: must be sent as a JSON array (e.g. ["a","b"]) even with a single value (["a"]). Bare scalars fail validation.
lastRenewedBy ID No - body lastRenewedBy
Description: ID of user (admin/mod) who last renewed or updated the subscription record; for audit.
paymentStatus Enum No - body paymentStatus
Description: Stripe payment status: pending (awaiting payment), paid (success), failed, canceled.
paymentStatusUpdatedAt Date No - body paymentStatusUpdatedAt
Description: Timestamp of the last payment status change from Stripe.
stripeSubscriptionId String No - body stripeSubscriptionId
Description: Stripe subscription ID for recurring billing management. Set after successful payment.

Parameter Transformations

Some parameters are post-processed using transform scripts after being read from the request but before validation or workflow execution. Only parameters with a transform script are listed below.

No parameters are transformed in this API.

AUTH Configuration

The authentication and authorization configuration defines the core access rules for the cancelCompanySubscription Business API. These checks are applied after parameter validation and before executing the main business logic.

While these settings cover the most common scenarios, more fine-grained or conditional access control—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like PermissionCheckAction, MembershipCheckAction, or ObjectPermissionCheckAction.

Login Requirement

This API requires login (loginRequired = true). Requests from non-logged-in users will return a 401 Unauthorized error. Login is necessary but not sufficient, as additional role, permission, or other authorization checks may still apply.

Ownership Checks

Role and Permission Settings

Where Clause

Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to get, list, update, and delete APIs. All API types except list are expected to affect a single record.

If nothing is configured for (get, update, delete) the id fields will be the select criteria.

Select By: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (get, update, delete), it defines how a unique record is located. In list APIs, it scopes the results to only entries matching the given values. Note that selectBy fields will be ignored if fullWhereClause is set.

The business api configuration has a selectBy setting: ‘[’']`

Full Where Clause An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When fullWhereClause is set, selectBy is ignored, however additional selects will still be applied to final where clause.

The business api configuration has no fullWhereClause setting.

Additional Clauses A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly.


// Additional Clause Name : TenantCompanyScope

// condition
// No condition defined — clause is applied unconditionally

// clause object
{ companyId: this.session.companyId }

Actual Where Clause This where clause is built using whereClause configuration (if set) and default business logic.

runMScript(() => ({$and:[{id:this.companySubscriptionId},{ companyId: this.session.companyId },{companyId:this.companyId,isActive:true}]}), {"path":"services[9].businessLogic[5].whereClause.fullWhereClause"})

Data Clause

Defines custom field-value assignments used to modify or augment the default payload for create and update operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings.

An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer.

Custom Data Clause Override

{
    status: runMScript(() => ('canceled'), {"path":"services[9].businessLogic[5].dataClause.customData[0].value"}),
    paymentStatus: runMScript(() => ('canceled'), {"path":"services[9].businessLogic[5].dataClause.customData[1].value"}),
    lastRenewedBy: runMScript(() => (this.session.userId), {"path":"services[9].businessLogic[5].dataClause.customData[2].value"}),
    amount: runMScript(() => ('10000'), {"path":"services[9].businessLogic[5].dataClause.customData[3].value"}),
   
}

Actual Data Clause

The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager.

{
  activationDate: this.activationDate,
  expiryDate: this.expiryDate,
  status: runMScript(() => ('canceled'), {"path":"services[9].businessLogic[5].dataClause.customData[0].value"}),
  subscribedFeatures: this.subscribedFeatures ? this.subscribedFeatures : 
                 ( this.subscribedFeatures_remove ? sequelize.fn('array_remove', sequelize.col('subscribedFeatures'), this.subscribedFeatures_remove) : (this.subscribedFeatures_append ? sequelize.fn('array_append', sequelize.col('subscribedFeatures'), this.subscribedFeatures_append) : undefined)) ,
  lastRenewedBy: runMScript(() => (this.session.userId), {"path":"services[9].businessLogic[5].dataClause.customData[2].value"}),
  paymentStatus: runMScript(() => ('canceled'), {"path":"services[9].businessLogic[5].dataClause.customData[1].value"}),
  paymentStatusUpdatedAt: this.paymentStatusUpdatedAt,
  stripeSubscriptionId: this.stripeSubscriptionId,
  amount: runMScript(() => ('10000'), {"path":"services[9].businessLogic[5].dataClause.customData[3].value"}),
}

Business Logic Workflow

[1] Step : startBusinessApi

Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution.

You can use the following settings to change some behavior of this step. apiOptions, restSettings, grpcSettings, kafkaSettings, sseSettings, cronSettings

[2] Action : fetchCurrentSubscription

Action Type: FetchObjectAction

Fetch the current subscription to validate state and get Stripe subscription ID.

class Api {
  async fetchCurrentSubscription() {
    // Fetch Object on childObject companySubscription

    const userQuery = {
      $and: [
        {
          id: runMScript(() => this.objectId, {
            path: "services[9].businessLogic[5].actions.fetchObjectActions[0].matchValue",
          }),
        },
        { isActive: true },
      ],
    };
    const { convertUserQueryToSequelizeQuery } = require("common");
    const scriptQuery = convertUserQueryToSequelizeQuery(userQuery);

    // get object from db
    const data = await getCompanySubscriptionByQuery(scriptQuery);

    if (!data) {
      throw new NotFoundError(
        "errMsg_FethcedObjectNotFound:companySubscription",
      );
    }

    return data
      ? {
          id: data["id"],
          companyId: data["companyId"],
          status: data["status"],
          paymentStatus: data["paymentStatus"],
          stripeSubscriptionId: data["stripeSubscriptionId"],
        }
      : null;
  }
}

[3] Action : ensureSubscriptionIsActive

Action Type: ValidationAction

Only allow canceling an active subscription.

class Api {
  async ensureSubscriptionIsActive() {
    let isValid;
    try {
      isValid = runMScript(
        () =>
          this.companySubscription &&
          this.companySubscription.status === "active" &&
          this.companySubscription.paymentStatus === "paid",
        {
          path: "services[9].businessLogic[5].actions.validationActions[0].validationScript",
        },
      );
    } catch (err) {
      throw new HttpServerError(
        `Validation 'ensureSubscriptionIsActive' script failed: ${err.message}`,
        err,
      );
    }

    if (!isValid) {
      throw new BadRequestError("Only active subscriptions can be canceled.");
    }
    return isValid;
  }
}

[4] Action : cancelStripeSubscription

Action Type: IntegrationAction

Cancel the Stripe subscription for the company.

class Api {
  async cancelStripeSubscription() {
    // Integration Action for stripe

    const input = {
      subscriptionId: runMScript(
        () => this.companySubscription.stripeSubscriptionId,
        {
          path: "services[9].businessLogic[5].actions.integrationActions[0].parameters[0].parameterValue",
        },
      ),
    };

    const stripeClient = await getIntegrationClient("stripe");
    return await stripeClient.cancelSubscription(input);
  }
}

[5] Step : readParameters

Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones.

You can use the following settings to change some behavior of this step. customParameters, redisParameters

[6] Step : transposeParameters

Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context.

[7] Step : checkParameters

Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met.

[8] Step : checkBasicAuth

Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update.

You can use the following settings to change some behavior of this step. authOptions

[9] Step : buildWhereClause

Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary.

You can use the following settings to change some behavior of this step. whereClause

[10] Step : fetchInstance

Manager fetches the existing record from the database and writes it to the context for validation or enrichment.

[11] Step : checkInstance

Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks.

[12] Step : buildDataClause

Manager prepares the data clause for the update, applying transformations or enhancements before persisting.

You can use the following settings to change some behavior of this step. dataClause

[13] Step : mainUpdateOperation

Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured.

[14] Step : buildOutput

Manager assembles the response object from the update result, masking fields or injecting additional metadata.

[15] Step : sendResponse

Manager sends the response back to the controller for delivery to the client.

[16] Step : raiseApiEvent

Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured.

Rest Usage

Rest Client Parameters

Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources.

The cancelCompanySubscription api has got 8 regular client parameters

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
activationDate Date false request.body?.[“activationDate”]
expiryDate Date false request.body?.[“expiryDate”]
status Enum false request.body?.[“status”]
subscribedFeatures String false request.body?.[“subscribedFeatures”]
lastRenewedBy ID false request.body?.[“lastRenewedBy”]
paymentStatusUpdatedAt Date false request.body?.[“paymentStatusUpdatedAt”]
stripeSubscriptionId String false request.body?.[“stripeSubscriptionId”]

REST Request

To access the api you can use the REST controller with the path PATCH /v1/cancelcompanysubscription/:companySubscriptionId

  axios({
    method: 'PATCH',
    url: `/v1/cancelcompanysubscription/${companySubscriptionId}`,
    data: {
            activationDate:"Date",  
            expiryDate:"Date",  
            status:"Enum",  
            subscribedFeatures:"String",  
            lastRenewedBy:"ID",  
            paymentStatusUpdatedAt:"Date",  
            stripeSubscriptionId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. For error handling, refer to the “Error Response” section.

Following JSON represents the most comprehensive form of the companySubscription object in the respones. However, some properties may be omitted based on the object’s internal logic.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}