iotoms Docs

Update a commission plan

PUT
/api/v1/commission/plans/{id}

Replaces a commission plan's name, rate structure, slabs and effective dates. Settlements that were already approved keep the rates they were calculated with; only future and draft runs see the change.

How to use it

  1. Get the plan ID from List commission plans and read the current setup with Get a commission plan.
  2. Send the full plan: name, rateStructure, flatRateBp (FLAT) or slabs (SLAB), effective dates and active.
  3. Draft runs pick up the new rates only when recalculated; approved runs keep the rates they were approved with.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

id*string

ID of the record (UUID).

Formatuuid

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 PUT 'https://beta.iotoms.com/api/v1/commission/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -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"  }}