iotoms Docs

Create an agreed price

POST
/api/v1/pricing/agreements

Records an agreed rate for a supplier or customer on an item or category, valid for a date window. Rejected if minQty is above 1, the currency differs from the tenant's, it overlaps an active agreement on the same key, or both or neither of item and category are set. Tax-inclusive rates are stored as entered.

How to use it

  1. Get the vendor ID from List vendors or customer number from List customers, and the item code from List items (or a category ID).
  2. Send partyRole, partyId, itemId or categoryId, rate, and the validFrom/validTo dates; pass actor in the query for audit.
  3. The agreement is ACTIVE and Resolve rates returns it as source AGREEMENT for documents dated in its window.
  4. The rate cannot be edited afterwards; use Revise an agreed price to change it.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Query Parameters

actor?string

Audit stamp for created_by

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

SUPPLIER for a purchase rate or CUSTOMER for a sale rate.

Value in"SUPPLIER""CUSTOMER"
partyId*string

Vendor ID for SUPPLIER (see List vendors) or customer number for CUSTOMER (see List customers). Must exist.

itemId?|

Item code the rate is for (see List items). Send either itemId or categoryId, not both.

categoryId?|

Category the rate is for (see List categories). Send either categoryId or itemId, not both.

uomId?|

Unit the rate is per (see List an item's units of measure). Omit for the item's base unit.

Formatuuid
currencyCode?|

Currency of the rate. Defaults to the merchant's currency; any other currency is rejected.

rate*number

Agreed price per unit, greater than 0. Stored to 4 decimals, exactly as entered (gross when taxInclusive).

taxInclusive*boolean

true (default) when the agreed rate includes tax.

minQty*number

Must be 1 (the default). Quantity breaks are not supported yet and any other value is rejected.

validFrom?|

First day the rate applies, YYYY-MM-DD. Defaults to today.

Formatdate
validTo?|

Last day the rate applies, YYYY-MM-DD, not before validFrom. Omit for open-ended.

Formatdate
source*string

How the rate was obtained: MANUAL (default), IMPORT or SUPPLIER_QUOTE. Informational only.

Value in"MANUAL""SUPPLIER_QUOTE""IMPORT"
sourceRef?|

Optional external reference, e.g. a quotation or contract number.

notes?|

Optional free-text 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' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "partyRole": "SUPPLIER",  "partyId": "string",  "rate": 0,  "taxInclusive": true,  "minQty": 0,  "source": "MANUAL"}'
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  }}