Transactions

The transactions endpoint returns sales or transaction records.
Transaction responses can include product references, event references, quantities, prices, invoice status and related custom report configuration.

GET /public/v1/api/transaction/all

Use cases

Use this endpoint to retrieve transaction data for external systems, for example:

sales quantities
product references
event references
transaction prices
invoice status
credit state
export processing state
custom report results
custom report field configuration

Response structure

The endpoint returns a list of transactions and a total count.

Example structure:

{
  "transactions": [
    {
      "_id": "637210f49335e500106249a4",
      "price": 13.9,
      "qty": 3,
      "invoice_status": "ReadyToInvoice",
      "eventId": "637200643e72fa00164004b6",
      "productId": "636e6cd33e72fa0016400469",
      "saleTime": "2022-11-14T09:57:00.000Z",
      "created": "2022-11-14T09:57:08.982Z"
    }
  ],
  "count": 414
}

Transaction fields

A transaction contains the basic sales information such as price, quantity, product reference and event reference.

Example:

{
  "_id": "637210f49335e500106249a4",
  "price": 13.9,
  "qty": 3,
  "eventId": "637200643e72fa00164004b6",
  "productId": "636e6cd33e72fa0016400469",
  "saleTime": "2022-11-14T09:57:00.000Z",
  "created": "2022-11-14T09:57:08.982Z",
  "date": "2022-11-14T09:57:08.982Z"
}

Product reference

Transactions reference products through the productId property.

Example:

{
  "productId": "636e6cd33e72fa0016400469"
}

Use this value to map the transaction to the related product in your external system.

note

Depending on the project and transaction type, a transaction may also include proxyProductName.

Event reference

Transactions reference the related event through the eventId property.

Example:

{
  "eventId": "637200643e72fa00164004b6"
}

Use this value to connect transactions with event data from the events endpoint.

GET /public/v1/api/event/all

Quantity and price

The transaction quantity is returned in qty.

The transaction price is returned in price.

Example:

{
  "price": 13.9,
  "qty": 3
}

The total value can be calculated by the external system:

total = price * qty

Invoice status

The invoice status is returned in invoice_status.

Example:

{
  "invoice_status": "ReadyToInvoice"
}

Common values can include states such as ready for invoice or already invoiced, depending on the transaction lifecycle in EMPPLAN.

Invoice references

If a transaction is already related to an invoice, invoice references may be included in invoice_id.

Example:

{
  "invoice_id": [
    "661543eb407dd600117c098f"
  ],
  "prev_invoice_id": "661543eb407dd600117c098f"
}

note

Invoice-related fields depend on the transaction state and may not be present on every transaction.

Credit state

Transactions can include credit-related fields.

Example:

{
  "credits": 0,
  "item_credit_state": false
}

Use these fields to detect whether a transaction has credit-related handling in the billing process.

Export details

The exportDetails object contains information about export processing.

Example:

{
  "exportDetails": {
    "processed": false
  }
}

This can be used by integrations to check whether a transaction was already processed or exported.

Custom report data

Transactions can include _customReport.

This object can contain:

submitted report values in reportResults
the related custom report configuration
the custom report configuration ID

Example:

{
  "_customReport": {
    "reportResults": {
      "636e70ff3e72fa0016400481": {
        "value": 3.5,
        "name": "Overall customer satisfaction",
        "fieldId": "636e70ff3e72fa0016400481"
      }
    },
    "_configcreatedTime": {
      "_id": "64be87ce9785940064c1e315",
      "type": "transactionFixedProduct",
      "name": "Product report",
      "customFields": []
    },
    "_customReportConfig": "64be87ce9785940064c1e315"
  }
}

info

The related custom report configuration is included in the transaction payload. This allows external systems to interpret dynamic reportResults fields without requiring a separate configuration endpoint for these responses.

Report results

The reportResults object contains submitted values for custom report fields.

Example:

{
  "reportResults": {
    "636e70ff3e72fa0016400481": {
      "value": 3.5,
      "name": "Overall customer satisfaction",
      "fieldId": "636e70ff3e72fa0016400481"
    },
    "636e73409335e50010624893": {
      "value": "64bf9e4324e8440090114309",
      "name": "Please take a photo of your promotion stand",
      "fieldId": "636e73409335e50010624893"
    }
  }
}

The key of each entry is the custom field ID.

Example:

"636e70ff3e72fa0016400481": {
  "value": 3.5,
  "name": "Overall customer satisfaction",
  "fieldId": "636e70ff3e72fa0016400481"
}

Custom report configuration

The custom report configuration can be included in:

_customReport._configcreatedTime

or, depending on the response shape:

_customReport._customReport._configcreatedTime

The configuration contains metadata about the custom report itself.

Example:

{
  "_configcreatedTime": {
    "_id": "64be87ce9785940064c1e315",
    "type": "transactionFixedProduct",
    "name": "Product report",
    "transactionConfig": {
      "useQty1": true
    },
    "customFields": []
  },
  "_customReportConfig": "64be87ce9785940064c1e315"
}

Custom fields

Custom field definitions are available in the customFields array of the custom report configuration.

Example:

{
  "customFields": [
    {
      "_id": "64be87ce9785940064c1e316",
      "config": {
        "_id": "636e70ff3e72fa0016400481",
        "name": "Overall customer satisfaction",
        "fieldType": "Slider",
        "fieldObject": {
          "options": [],
          "minimum": 0,
          "maximum": 5,
          "step": 0.5
        }
      },
      "required": false,
      "pdf": true
    }
  ]
}

How to map `reportResults`

The reportResults object uses the custom field ID twice:

as the object key
as fieldId inside the result object

Example:

{
  "reportResults": {
    "636e70ff3e72fa0016400481": {
      "value": 3,
      "name": "Overall customer satisfaction",
      "fieldId": "636e70ff3e72fa0016400481"
    }
  }
}

Both values identify the submitted custom field.

The field definition can be found in the custom report configuration under:

_customReport._configcreatedTime.customFields

customFields is an array.
Each item contains a config object.
The config._id value is the field ID that matches the reportResults key or reportResults[].fieldId.

Recommended matching logic:

reportResults[FIELD_ID].fieldId === _customReport._configcreatedTime.customFields[*].config._id

or:

Object.keys(reportResults)[*] === _customReport._configcreatedTime.customFields[*].config._id

Example result value

{
  "fieldId": "636e70ff3e72fa0016400481",
  "name": "Overall customer satisfaction",
  "value": 3
}

Matching field configuration

{
  "layout": {
    "cols": 1,
    "rows": 2,
    "inline": 100
  },
  "visibility": {
    "conditions": {
      "productGroups": [],
      "products": [],
      "hideForDealerRanks": [],
      "field": {
        "type": "group",
        "operator": "AND",
        "rKey": "0.6581692781221842",
        "conditions": []
      }
    },
    "config": {
      "multiplyForEachCondition": true,
      "groupByConditions": false
    }
  },
  "_id": "64be87ce9785940064c1e316",
  "config": {
    "_id": "636e70ff3e72fa0016400481",
    "name": "Overall customer satisfaction",
    "fieldType": "Slider",
    "slug": "",
    "toolTipTxt": "",
    "description": "",
    "active": true,
    "enableHintOnClick": true,
    "fieldObject": {
      "options": [],
      "minimum": 0,
      "maximum": 5,
      "step": 0.5
    },
    "created": "2022-11-11T15:57:51.802Z"
  },
  "pdf": true,
  "required": false,
  "requiredByFieldId": null,
  "relatedReport": null
}

In this example, the submitted value belongs to the field:

Overall customer satisfaction

The field type is:

Slider

This means the external system can correctly interpret the value as a slider value with the configured range:

{
  "minimum": 0,
  "maximum": 5,
  "step": 0.5
}

tip

Always resolve reportResults against _customReport._configcreatedTime.customFields[].config._id before interpreting the value. This is how you can determine whether the submitted value belongs to a slider, number field, text field, upload field or another custom field type.

If fieldId is not present inside the result object, use the object key from reportResults as the field ID.

Upload fields

For upload fields, the submitted value can be a file reference ID.

Example:

{
  "636e73409335e50010624893": {
    "value": "64bf9e4324e8440090114309",
    "name": "Please take a photo of your promotion stand",
    "fieldId": "636e73409335e50010624893"
  }
}

The matching field configuration may look like this:

{
  "config": {
    "_id": "636e73409335e50010624893",
    "name": "Please take a photo of your promotion stand",
    "fieldType": "upload",
    "fieldObject": {
      "options": [],
      "config": {
        "forceGps": true,
        "preferMetaGpsLocationData": true
      }
    }
  }
}

Slider fields

For slider fields, the submitted value is usually numeric.

Example result:

{
  "value": 3.5,
  "name": "Overall customer satisfaction",
  "fieldId": "636e70ff3e72fa0016400481"
}

Example configuration:

{
  "fieldType": "Slider",
  "fieldObject": {
    "minimum": 0,
    "maximum": 5,
    "step": 0.5
  }
}

Transaction report types

The custom report configuration can contain a type.

Example:

{
  "type": "transactionFixedProduct",
  "name": "Product report",
  "transactionConfig": {
    "useQty1": true
  }
}

Another possible type is:

{
  "type": "sales",
  "name": "Transactions"
}

Use the type value to understand how the transaction report was configured in EMPPLAN.

Pagination and debug information

The response can include debug information about the query.

Example:

{
  "count": 414,
  "debug": {
    "query": {
      "skip": 0,
      "eventId": "64c7780d01632f00b243f528",
      "limit": 25,
      "type": "sale"
    }
  }
}

The count value indicates the number of matching transactions.

Recommended mapping strategy

When integrating transactions into an external system, use these fields as stable mapping references:

Purpose	Field
Transaction ID	`_id`
Event ID	`eventId`
Product ID	`productId`
Price	`price`
Quantity	`qty`
Sale time	`saleTime`
Created date	`created`
Invoice status	`invoice_status`
Invoice ID	`invoice_id`
Previous invoice ID	`prev_invoice_id`
Credit state	`item_credit_state`
Export processed state	`exportDetails.processed`
Custom report configuration ID	`_customReport._customReportConfig`
Custom report results	`_customReport.reportResults`
Custom field definitions	`_customReport._configcreatedTime.customFields[].config`

Summary

The transactions endpoint provides transaction data together with related custom report configuration.

Most importantly:

transaction records are returned in transactions
event references are available through eventId
product references are available through productId
invoice state is available through invoice_status
credit state is available through item_credit_state
custom report values are available through _customReport.reportResults
custom report field configuration is included in _customReport._configcreatedTime.customFields[].config

For integrations, the recommended approach is to map transaction data by _id, eventId and productId, and to interpret custom report values by matching the reportResults key or fieldId against _customReport._configcreatedTime.customFields[].config._id.

Use cases​

Response structure​

Transaction fields​

Product reference​

Event reference​

Quantity and price​

Invoice status​

Invoice references​

Credit state​

Export details​

Custom report data​

Report results​

Custom report configuration​

Custom fields​

How to map reportResults​

Example result value​

Matching field configuration​

Upload fields​

Slider fields​

Transaction report types​

Pagination and debug information​

Recommended mapping strategy​

Summary​

Use cases

Response structure

Transaction fields

Product reference

Event reference

Quantity and price

Invoice status

Invoice references

Credit state

Export details

Custom report data

Report results

Custom report configuration

Custom fields

How to map `reportResults`

Example result value

Matching field configuration

Upload fields

Slider fields

Transaction report types

Pagination and debug information

Recommended mapping strategy

Summary