iotoms Docs

Start a commission settlement run

POST
/api/v1/commission/settlements

Creates a draft settlement for the period periodFrom–periodTo, computing each assigned person's commission on money actually collected, net of tax and returns. Rejected if the period is invalid or overlaps an already-approved run.

How to use it

  1. Make sure salespeople are on a plan for the period (List commission plan assignments).
  2. Send periodFrom and periodTo (YYYY-MM-DD) and optional notes. The period must not overlap an approved run.
  3. A DRAFT run is created with one line per assigned person, based on money collected net of tax and returns.
  4. Review it with Get a commission settlement run, then recalculate, approve or delete the draft.

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
periodFrom*string

First day of the period to settle (YYYY-MM-DD).

Formatdate
periodTo*string

Last day of the period to settle (YYYY-MM-DD); must not be before periodFrom.

Formatdate
notes?|

Optional free-text notes for the run.

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 settlement run with every person's commission line.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/commission/settlements' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "periodFrom": "2019-08-24",  "periodTo": "2019-08-24"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "periodFrom": "2019-08-24",    "periodTo": "2019-08-24",    "status": "DRAFT",    "totalCommission": 0,    "totalPaid": 0,    "notes": "string",    "lines": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "userRef": "string",        "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",        "planName": "string",        "rateStructure": "FLAT",        "rateBp": 0,        "collectedBase": 0,        "returnsBase": 0,        "netBase": 0,        "commissionAmount": 0,        "paidAmount": 0,        "status": "DRAFT",        "uncollectedCredit": 0,        "sources": [          {            "sourceType": "SALE_COLLECTION",            "documentId": "4704590c-004e-410d-adf7-acb7ca0a7052",            "documentDate": "2019-08-24",            "documentRef": "string",            "grossAmount": 0,            "baseAmount": 0          }        ]      }    ],    "createdAt": "2019-08-24T14:15:22Z",    "createdBy": "string",    "approvedAt": "2019-08-24T14:15:22Z",    "approvedBy": "string"  }}