Create a transaction from a cart
Finalises a cart into a sale. The totals you send must match the cart's server-computed totals or the call is rejected. Idempotent on clientTransactionId: resending returns the existing sale; a second sale for the same cartId is refused. Creating a sale also deducts stock from the register's stockroom.
How to use it
- Build the sale in a cart with Create a cart and Update a cart, and read its server-computed totals with Get a cart.
- Optionally record the payment with Record a payment collection and pass its id as paymentId.
- Send cartId, a unique clientTransactionId, channel, contextType, businessDate and totals exactly matching the cart (add the *Cents fields for an exact check).
- On success the sale is recorded, counted in the daily summary and its stock is deducted from the register's stockroom; stock problems are logged for review rather than blocking the sale.
- If the response is lost, resend with the same clientTransactionId to get the same sale back; the cart cannot be turned into a second sale.
BearerAuthAuthorizationBearer <JWT>application/json- body
cartId*stringRequired. Id of the cart being finalised, from Create a cart. A second sale for the same cart is refused.
clientTransactionId?|Your own unique id for the sale. Resending the same id returns the sale already recorded instead of an error.
channel*stringRequired. LINE_DISTRIBUTION (van/route selling), POS (shop till), ECOM (online) or OTHER.
"LINE_DISTRIBUTION""POS""ECOM""OTHER"contextType*stringRequired. STORE_VISIT, POS_ORDER or ECOM_DELIVERY (older values DAY_CYCLE, STORE, ORDER_RETURN, TRANSACTION, OTHER still accepted). See Get payment reference data.
"STORE_VISIT""POS_ORDER""ECOM_DELIVERY""DAY_CYCLE""STORE""ORDER_RETURN""TRANSACTION""OTHER"businessDate*stringRequired. Trading date the sale counts towards, YYYY-MM-DD.
datedayCycleId?|Optional day cycle the sale belongs to, from Get the active day cycle.
uuidstoreId?|Optional store or customer store the sale was made at.
int64storeName?|Optional store name to record on the sale.
registerId?|Register that made the sale, from List registers. Stock is deducted from its stockroom (or the default warehouse if it has none).
int64customerNumber?|Optional customer number of the buyer, from List customers.
invoiceNumber?|Optional invoice number printed on the receipt by the selling device.
subtotal*numberRequired. Must equal the cart's subtotal in the merchant's currency (within 0.01 unless subtotalCents is sent).
taxTotal*numberRequired. Must equal the cart's tax total in the merchant's currency.
discountTotal*numberRequired. Must equal the cart's discount total in the merchant's currency.
grandTotal*numberRequired. Must equal the cart's grand total in the merchant's currency.
paymentStatus*stringRequired. Paid, Unpaid (sold on credit) or Refunded.
"Paid""Unpaid""Refunded"paymentId?|Optional id of a payment from Record a payment collection. When given, cash collected, credit issued and payment split are taken from it.
uuidcashCollected?|Cash received, in the merchant's currency. Ignored when paymentId is given; defaults to 0.
creditIssued?|Amount put on the customer's credit, in the merchant's currency. Ignored when paymentId is given; defaults to 0.
paymentMode?|Optional payment method summary, e.g. CASH. When left out it is derived from the linked payment (one method, or MIXED).
syncStatus?|Optional sync state from the selling device, stored as sent.
soldBy?|Optional username of the salesperson to credit. Defaults to the signed-in user. Does not affect any amount.
subtotalCents?|Optional subtotal in hundredths of the currency unit (1050 = 10.50). When sent, the totals check is exact instead of allowing a 0.01 difference.
int64taxTotalCents?|Optional tax total in hundredths of the currency unit (1050 = 10.50). When sent, it is compared exactly with the cart.
int64discountTotalCents?|Optional discount total in hundredths of the currency unit (1050 = 10.50). When sent, it is compared exactly with the cart.
int64grandTotalCents?|Optional grand total in hundredths of the currency unit (1050 = 10.50). When sent, it is compared exactly with the cart.
int64cashCollectedCents?|Optional cash collected in hundredths of the currency unit (1050 = 10.50), sent alongside cashCollected.
int64creditIssuedCents?|Optional credit issued in hundredths of the currency unit (1050 = 10.50), sent alongside creditIssued.
int64OK
*/*- response
status*stringOutcome of the call: SUCCESS when the request was handled, ERROR otherwise.
message*stringShort human-readable message describing the outcome, e.g. which record was fetched or saved.
data?The transaction.
curl -X POST 'https://beta.iotoms.com/api/v1/transaction/transactions' \ -H 'Content-Type: application/json' \ -d '{ "cartId": "string", "channel": "LINE_DISTRIBUTION", "contextType": "STORE_VISIT", "businessDate": "2019-08-24", "subtotal": 0, "taxTotal": 0, "discountTotal": 0, "grandTotal": 0, "paymentStatus": "Paid"}'{ "status": "string", "message": "string", "data": { "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc", "cartId": "string", "clientTransactionId": "string", "channel": "LINE_DISTRIBUTION", "contextType": "STORE_VISIT", "businessDate": "2019-08-24", "dayCycleId": "bbed7a30-80be-4ccf-810d-a33c370a67d1", "storeId": 0, "storeName": "string", "registerId": 0, "customerNumber": "string", "invoiceNumber": "string", "subtotal": 0, "taxTotal": 0, "discountTotal": 0, "grandTotal": 0, "paymentStatus": "Paid", "cashCollected": 0, "creditIssued": 0, "paymentMode": "string", "syncStatus": "string", "soldBy": "string", "createdAt": "2019-08-24T14:15:22Z", "lines": [ { "itemId": "string", "description": "string", "quantitySold": 0, "unitPrice": 0, "discountAmount": 0, "taxAmount": 0, "lineSubtotal": 0, "lineTotal": 0, "quantityReturned": 0, "quantityReturnable": 0 } ], "payments": [ { "mode": "CASH", "amount": 0 } ], "returnSummary": { "totalReturnedAmount": 0, "returnCount": 0, "status": "string" } }}