Add Party sale

Description

This service records a new sale for the logged-in party. A separate sale record is created for each item included in the request's items array.

---

Request

Restrictions

This service requires an authenticated user and can only be called after a successful consumer login.

Endpoint

POST https://<server-url>/api/v4/sale/add/partySale

Parameters

Parameter	Location	Description
touchpoint	Query / Header	The identifier for the touchpoint. Use Thalamus-Touchpoint for the header.
token	Query / Header	The authentication token for the API session. Use Thalamus-Token for the header.

Full URL Example

https://<server-url>/api/v4/sale/add/partySale?touchpoint=test&token=...

Request Body

The request body contains the details of the overall sale transaction and an array of items sold.

Top-Level Fields

Field	Type	Description
salesOriginId	Integer	The ID of the sale's origin.
saleDate	Timestamp	The date of the sale.
vendorId	Integer	The ID of the vendor.
paymentMethodId	Integer	The ID of the payment method.
currencyId	Integer	The ID of the currency used.
transactionId	String	A unique external identifier for the transaction.
physicalLocationId	Integer	Location Option 1. The ID of the physical location where the sale occurred.
principal	String	Location Option 2. The principal of the physical location (e.g., systemId|987).
description1-10	String	Optional. Custom description fields for the sale.
items	Array	An array of item objects sold in the transaction. See structure below.

items Array Object Fields

Field	Type	Description
referenceCodeName	String	The reference code for the item (e.g., "SKU-Reference-1").
skuCode	String	The specific SKU code of the item.
quantity	Integer	The number of units sold.
amount	Number	The total amount for this line item.

JSON

{
  "salesOriginId": 1,
  "saleDate": 1647869161,
  "vendorId": 2,
  "paymentMethodId": 1,
  "currencyId": 1,
  "transactionId": "jfj7-fbde4-rgvaeb-34tvss",
  "physicalLocationId": 24,
  "description1": "description1",
  "items": [
    {
      "referenceCodeName": "SKU-Reference-1",
      "skuCode": "Code1",
      "quantity": 10,
      "amount": 100.50
    },
    {
      "referenceCodeName": "SKU-Reference-2",
      "skuCode": "Code2",
      "quantity": 20,
      "amount": 200.50
    }
  ]
}

---

Response

✅ Successful Response: 201 Created

The sale was successfully created. The response returns the standard session context and a salesLimitExceeded array. This array will be populated if any items in the sale exceeded a defined purchasing limit.

salesLimitExceeded Object Fields

Field	Type	Description
sku	String	The SKU of the item that exceeded a limit.
limittype	String	The type of limit that was exceeded (e.g., "Day").
limitfrecuency	String	The metric of the limit (e.g., "quantity").
limitmaxvalue	Number	The maximum value allowed by the limit.
limitexceededvalue	Number	The cumulative value that caused the limit to be exceeded.

JSON

{
  "context": {
    "links": [
      {
        "ref": "home",
        "href": "/api/v4/people/home"
      }
    ],
    "simpleProfile": {
      "firstname": "Firstname",
      "lastname": "Lastname",
      "email": "[email protected]"
    }
  },
  "salesLimitExceeded": [
    {
      "id": 1,
      "sku": "Code1",
      "quantity": 10,
      "amount": 100.5,
      "refcode": "SKU-Reference-1",
      "limittype": "Day",
      "limitfrecuency": "quantity",
      "limitmaxvalue": 500,
      "limitexceededvalue": 18525
    }
  ]
}

❌ Unsuccessful Response: 400 Bad Request

Returned if any of the provided IDs (e.g., vendorId, salesOriginId, physicalLocationId) are invalid, or if the JSON is malformed.

JSON

{
  "errors": {
    "vendorId": "InvalidId",
    "execution.vendorId": "Vendor Id: Invalid ID"
  }
}