Adding Sales/Metric Data to Deputy

You can add the following metric data via this API including:
Budget - Hours or Wages
Sales - Actual or Forecast or Manager Forecast Sales
Required Staff - The counter of required staff

Any custom Metric - Eg: Actual or Forecast or Manager Forecast Transactions or FootTraffic etc. Please be mindful you will need to create the custom metric in Business Insights first before you use this API to insert your data.

Adding metric data via the API is a simple process but you will need a few pieces of information before you can successfully save the data:

area - In the Deputy application, this is called an Area. If you want to track sales against a specific Area in Deputy you will need to include this item. In other API requests this is called the OperationalUnit. To get a list of areas use the Get Operational Units endpoint.
employee - The id of the employee in the Deputy install. If you do not include an employee, the sales data will be saved against whoever authorised the API connection ie: Whoever authorised the Oauth connection.
timestamp - The timestamp of the sale in epoch time. It is important this is correct because many Deputy users track sales per hour when comparing labour costs.
value - The amount of the sale
type - This is typically "Sales" however if the Deputy install has a custom metric, this can be defined here eg: "Transactions". Please check the tips below for how to set the correcat type for your metric data.
reference - A reference for the transaction. This should be unique (if it is not unique the original transaction with that reference will be overwritten).
location - This is the location within Deputy where the sale should be attributed. In other API requests you may see this referred to as Company. To get a list of locations use the Get Locations endpoint.

📘

How to set the correct type for your metric data

Any metric data including Sales and your own custom metric can have 3 different types:
Actual - type should be set as the metric name, Eg: Sales or Transactions
Forecast - type should be set with the prefix forecast , Eg: forecast_Sales or forecast_Transactions
Manager Forecast - type should be set with the prefix plan , Eg: plan_Sales or plan_Transactions
Forecast data can not be modified by any users via Business Insights.
Manager Forecast data can be modified by users via Business Insights if needed.

For Budget data, you should set the type as below:
Budget Hour - type should be set as budget_StaffHour
Budget Wage - type should be set as budget_Wage

For Required Staff, you should set the type as "StaffNumber"

Retrieving the Locations from the Deputy install (Operational Units)

If you want to save metric data against specific areas in Deputy, you will need to have the operational unit ID as an integer. You can retrieve the operational units of an install using the Get Operational Units endpoint detailed here.

Adding Actual Sales via the API

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v2/metrics'

{
    "data": [
        {
            "timestamp": 1660272300,
            "area": 2,
            "type": "Sales",
            "reference": "Sales-ManualEntry-1660272300",
            "value": 100.30,
            "employee": 1,
            "location": 1
        }
    ]
}

If the actual sales data is added successfully, you will get a response including information about the data that was saved, including an id of the record, which employee the sale was recorded against as well as the area (OperationalUnit).

{
    "success": true,
    "data": [
        {
            "timestamp": "1660272300",
            "employee": 1,
            "area": 2,
            "type": "Sales",
            "reference": "Sales-ManualEntry-1660272300",
            "value": 100.30,
            "state": "ACTUAL",
            "location": 1,
            "id": "2DFDMyGzI7c40PKYDl2M8QUGlGt",
            "created": "2022-08-12T06:31:34Z",
            "modified": "2022-08-12T06:31:34Z"
        }
    ]
}

It's also possible to add many sales at once by appending :bulk to the end of the API url. When this is the case just include multiple objects in the array.

❗️

Bulk API

When using the bulk API method, the data may not be ready for retrieval or display within Deputy immediately. If you need real-time saving you should use the regular API url

Data Elements

Adding Forecast Sales or Transactions via the API

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v2/metrics'

{
    "data": [
        {
            "timestamp": 1660272300,
            "area": 2,
            "type": "plan_Sales", // or "plan_Transactions" for manager forecast Transactions, or "forecast_Transactions" for forecast Transactions.
            "reference": "Sales-ManualEntry-1660272300",
            "value": 100.30,
            "employee": 1,
            "location": 1
        }
    ]
}

If the forecast data is saved successfully, you will get the response as below

{
    "success": true,
    "data": [
        {
            "timestamp": "1660272300",
            "employee": 1,
            "area": 2,
            "type": "plan_Sales",// or "plan_Transactions" for manager forecast Transactions, or "forecast_Transactions" for forecast Transactions.
            "reference": "Sales-ManualEntry-1660272300",
            "value": 100.30,
            "state": "PLAN",
            "location": 1,
            "id": "2DFDMyGzI7c40PKYDl2M8QUGlGt",
            "created": "2022-08-12T06:31:34Z",
            "modified": "2022-08-12T06:31:34Z"
        }
    ]
}

Adding Required Staff counter via the API

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v2/metrics'

{
    "data": [
        {
            "timestamp": 1660272300,
            "area": 2,
            "type": "StaffNumber", // Required Staff Counter
            "reference": "RequiredStaff-ManualEntry-1660272300",
            "value": 10,  // 10 required staff
            "employee": 1,
            "location": 1
        }
    ]
}

How to handle refunds

There are two ways you can handle refunds via the Deputy API. You can choose to send a 0.00 amount for the same sales reference as the original sale (this will update the original transaction) or you can send a negative sale amount with a different reference.

Your use case will determine which option to use because each option can have a different impact on the overall net sale amount displayed in Deputy, especially when the refund/return is done on a different day to the original sale.

In the scenario where the refund/return is on a different day to the original sale, a key decision to make is do you want the refund to be applied into the sales data on the same day as the original sale, or do you want it to apply to the current working day.

🚧

Partial refunds

If you need to perform a partial refund, the best way to handle this is a modification of the original sales transaction by including the same sales reference in the update request.

Sending a 0 dollar refund to Deputy

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v2/metrics'

Sample sales request sending a 0 dollar update

{
    "data": [
        {
            "timestamp": 1660272300,
            "area": 2,
            "type": "Sales",
            "reference": "Sales-ManualEntry-1660272300",
            "value": 0,
            "employee": 1,
            "location": 1
        }
    ]
}

🚧

Locations/Areas Update

It's possible to update the areas/locations of a transaction via the update process, to do this just update the records. If there is no change then include the original data with the payload.

The response will be the same as a brand new transaction, however have the same sales reference and the updated data.