iotoms Docs

Revise an agreed price

POST
/api/v1/pricing/agreements/{id}/revise

Changes an agreed rate without overwriting history: the current agreement is closed the day before the new rate starts and a new agreement linked to it is created. Returns the new agreement.

How to use it

  1. Find the ACTIVE agreement's ID with List agreed prices.
  2. Send the new rate and the date it starts (validFrom, after the current start; defaults to today).
  3. The current agreement becomes SUPERSEDED and ends the day before; a new ACTIVE agreement linked to it is returned.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

id*string

ID of the record (UUID).

Formatuuid

Query Parameters

actor?string

Name or username of the person making the change, stored on the agreement for audit.

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
rate*number

New agreed price per unit, greater than 0.

validFrom?|

Date the new rate starts, YYYY-MM-DD. Must be after the current agreement's start. Defaults to today.

Formatdate
validTo?|

Last day of the new rate, YYYY-MM-DD. Omit for open-ended.

Formatdate
taxInclusive?|

Whether the new rate includes tax. Omit to keep the current setting.

notes?|

Notes for the new agreement. Omit to copy the current agreement's notes.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The agreed price. For a revision this is the new agreement, not the one it replaced.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/pricing/agreements/497f6eca-6276-4993-bfeb-53cbbbba6f08/revise' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "rate": 0}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "partyRole": "SUPPLIER",    "partyId": "string",    "partyName": "string",    "itemId": "string",    "itemName": "string",    "categoryId": "string",    "uomId": "4df47f00-a69d-4ff2-b50d-4a7649a4b70c",    "uomCode": "string",    "currencyCode": "string",    "rate": 0,    "taxInclusive": true,    "minQty": 0,    "validFrom": "2019-08-24",    "validTo": "2019-08-24",    "status": "ACTIVE",    "supersedesId": "688cf67a-2e6c-4e49-8750-5bc8809fcd6f",    "supersededById": "af9b715c-a460-4411-a694-40645ca4c9a7",    "source": "MANUAL",    "sourceRef": "string",    "notes": "string",    "createdBy": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedBy": "string",    "updatedAt": "2019-08-24T14:15:22Z",    "inForceToday": true  }}