iotoms Docs

Change a merchant's plan

PUT
/api/v1/merchant/{merchantCode}/plan

Assigns a different subscription plan tier to the merchant identified by merchantCode and returns the new assignment. Returns 409 if the merchant has more active registers than the new plan allows, or 404 if the merchant does not exist. Feature access for the merchant's roles is updated to match the new plan.

How to use it

  1. Pick the new tier from List subscription plans and check its registerLimit against the merchant's active registers.
  2. Send planTier, and optionally assignedBy to record who made the change.
  3. If more registers are active than the new plan allows, the call returns 409 with the allowed limit and current usage; deactivate registers first or choose a larger plan.
  4. On success the plan takes effect at once and feature access for the merchant's roles is updated to match the new plan.

Path Parameters

merchantCode*string

The merchant's unique code, as chosen in Create a merchant account.

Request Body

application/json
  1. body
planTier*string

Subscription plan tier: FREE, BASIC, STANDARD, PLUS, PRO, PREMIUM, BUSINESS, ENTERPRISE, ULTIMATE, ELITE, or DISTRIBUTION (the FMCG distributor bundle). Required.

Value in"FREE""BASIC""STANDARD""PLUS""PRO""PREMIUM""BUSINESS""ENTERPRISE""ULTIMATE""ELITE""DISTRIBUTION"
assignedBy?|

Optional note of who made the change (for example an admin email). Stored with the assignment for audit.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request worked, ERROR when it did not.

message*string

Short human-readable message describing the result, for logs or display; do not parse it.

data?

The merchant's current plan assignment: tier, register limit, included features and features per role.

Example Request
curl -X PUT 'https://beta.iotoms.com/api/v1/merchant/string/plan' \  -H 'Content-Type: application/json' \  -d '{  "planTier": "FREE"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "merchantCode": "string",    "planTier": "FREE",    "registerLimit": 0,    "assignedAt": "2019-08-24T14:15:22Z",    "assignedBy": "string",    "features": [      {        "code": "string",        "name": "string",        "description": "string",        "category": "string"      }    ],    "featuresByRole": {      "property1": [        {          "code": "string",          "name": "string",          "description": "string",          "category": "string"        }      ],      "property2": [        {          "code": "string",          "name": "string",          "description": "string",          "category": "string"        }      ]    }  }}