Sales Data

Create Sales Data

Create a batch of sales data records (actual sales and/or forecasts) for an organisation.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/sales_data

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

Create a batch of sales data records (actual sales and/or forecasts) for an organisation.

Validation is all-or-nothing: if any record in the batch is invalid, the entire batch is rejected and no records are written.

Resubmitting a record updates the existing one instead of creating a duplicate:

Records of type actual are deduplicated by transaction_id when supplied, otherwise by the combination of (work_site_id, category_name, start_time)
Records of type forecast are always deduplicated by (work_site_id, category_name, start_time); any transaction_id supplied is ignored

Only records submitted with the default category_name of Gross Sales are included in the aggregated sales summary and demand forecast used elsewhere in Rostering. Records submitted under any other category_name are stored for reporting purposes only.

sales_dataobject[]required

Batch of sales data records to submit. Between 1 and 20,000 records per request

Response Body

Returns 201 if at least one new record was created, or 200 if every record in the batch already existed and was updated. The response always returns the pagination envelope for consistency with the List Sales Data API, though item_per_page, page_index, total_pages and total_items are always null for this endpoint.

dataobject

itemsobject[]

work_site_iduuid

ID of the work site the sales data record belongs to

start_timedatetime

Start time of the sales data record

typeenum<string>

Type of the sales data record

sales_amountnumber

Sales amount for the record

transaction_idstring

Transaction ID supplied for an actual sales record. Always null for forecast records

category_namestring

Name of the sales category the record belongs to. Defaults to Gross Sales when not supplied

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/sales_data" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "sales_data": [      {        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-14T09:00:00.000Z",        "type": "actual",        "sales_amount": 1234.56,        "transaction_id": "pos-txn-98765",        "category_name": "Food & Beverage"      },      {        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-15T00:00:00.000Z",        "type": "forecast",        "sales_amount": 5000      }    ]  }'

Response

{  "data": {    "items": [      {        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-14T09:00:00.000Z",        "type": "actual",        "sales_amount": 1234.56,        "transaction_id": "pos-txn-98765",        "category_name": "Food & Beverage"      },      {        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-15T00:00:00.000Z",        "type": "forecast",        "sales_amount": 5000,        "transaction_id": null,        "category_name": "Gross Sales"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 2,    "total_pages": 1  }}

Get Sales Data

List sales data submitted for a work site within a date range. The result is paginated.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/sales_data

Path Parameters

organisation_iduuidrequired

ID of the organisation

Query Parameters

work_site_iduuidrequired

ID of the work site to list sales data for

start_datestringrequired

Start date of the range in ISO-8601 format (inclusive)

end_datestringrequired

End date of the range in ISO-8601 format (inclusive). Must not be more than 3 months after start_date

typeenum<string>

Filter by record type. Returns both actual and forecast records when omitted

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

The sales data for the given work site and date range

dataobject

itemsobject[]

work_site_iduuid

ID of the work site the sales data record belongs to

start_timedatetime

Start time of the sales data record

typeenum<string>

Type of the sales data record

sales_amountnumber

Sales amount for the record

transaction_idstring

Transaction ID supplied for an actual sales record. Always null for forecast records

category_namestring

Name of the sales category the record belongs to. Defaults to Gross Sales when not supplied

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/sales_data" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-14T09:00:00.000Z",        "type": "actual",        "sales_amount": 1234.56,        "transaction_id": "pos-txn-98765",        "category_name": "Food & Beverage"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}