iotoms Docs

Create a commission plan

POST
/api/v1/commission/plans

Creates a commission plan with either a flat rate (flatRateBp, in basis points) or a list of slabs, plus effective dates. Commission is always calculated on net sales excluding tax.

How to use it

  1. Choose rateStructure: FLAT with flatRateBp (250 = 2.50%), or SLAB with contiguous bands starting at 0.
  2. Send name, effectiveFrom, optional effectiveTo and active.
  3. Assign salespeople to the new plan with Assign a person to a commission plan.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
name*string

Plan name. Required and cannot be blank.

rateStructure*string

FLAT for one rate on the whole base; SLAB for marginal rate bands.

Value in"FLAT""SLAB"
flatRateBp?|

Required for FLAT and not allowed for SLAB. Rate in basis points, 0 to 10000 (250 = 2.50%).

Formatint32
slabs*array<>

Required for SLAB and must be empty for FLAT. Bands must start at 0, be contiguous, and only the last may be open-ended.

effectiveFrom*string

First date the plan applies (YYYY-MM-DD).

Formatdate
effectiveTo?|

Optional last date the plan applies (YYYY-MM-DD); must not be before effectiveFrom. Omit for open-ended.

Formatdate
active*boolean

Whether the plan is in use. Defaults to true; inactive plans are ignored by new settlement runs.

Response Body

OK

*/*
  1. response
status*string

Outcome of the request: SUCCESS when it worked; errors return an error status with the reason in message.

message*string

Short human-readable message describing the outcome.

data?

The commission plan.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/commission/plans' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "rateStructure": "FLAT",  "slabs": [    {      "fromAmount": 0,      "rateBp": 0    }  ],  "effectiveFrom": "2019-08-24",  "active": true}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "basis": "NET_SALES_EXCL_TAX",    "rateStructure": "FLAT",    "flatRateBp": 0,    "slabs": [      {        "seq": 0,        "fromAmount": 0,        "toAmount": 0,        "rateBp": 0      }    ],    "payoutCycle": "MONTHLY",    "effectiveFrom": "2019-08-24",    "effectiveTo": "2019-08-24",    "active": true,    "assignedCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}