Sales Data

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Sales Data

Retrieve sales forecast and actual data for a location within a date range. This endpoint provides daily breakdowns of sales figures, budgeted hours, and costs.

Query Parameters:

Parameter Type Required Description
startTime DateTime! Yes Start of the date range (inclusive)
endTime DateTime! Yes End of the date range (inclusive)

Response Fields:

Field Description
day Date of the sales data (YYYY-MM-DD format)
forecast Forecasted sales amount (in cents)
actual Actual sales amount (in cents)
hours Budgeted hours for the day
cost Budgeted cost for the day (in cents)

Implementation Notes:

  • The X-Location-ID header is required to specify which location's sales data to query
  • Times are in ISO 8601 format with timezone information
  • Sales amounts are stored in cents (divide by 100 to get dollar amounts)
  • The query returns one record per day within the specified date range
  • Days without sales data will not be included in the results
  • The date range is inclusive of both start and end times
  • This data is typically used for workforce planning and performance analysis
  • Sales data can be compared against roster costs to calculate labor efficiency

GraphQL Query

query SalesForecast($startTime: DateTime!, $endTime: DateTime!) {
  locationSales(startTime: $startTime, endTime: $endTime) {
    day
    forecast
    actual
    hours
    cost
  }
}

Example Variables

{
  "startTime": "2024-05-18T16:00:00.000Z",
  "endTime": "2024-05-26T17:59:59.000Z"
}

Example Response

{
  "data": {
    "locationSales": [
      {
        "day": "2024-05-19",
        "forecast": 190000,
        "actual": 240000,
        "hours": 0,
        "cost": 0
      },
      {
        "day": "2024-05-20",
        "forecast": 170000,
        "actual": 165000,
        "hours": 24,
        "cost": 0
      },
      {
        "day": "2024-05-21",
        "forecast": 165000,
        "actual": 175500,
        "hours": 28,
        "cost": 0
      },
      {
        "day": "2024-05-22",
        "forecast": 120000,
        "actual": 145000,
        "hours": 24,
        "cost": 0
      },
      {
        "day": "2024-05-23",
        "forecast": 195000,
        "actual": 176500,
        "hours": 29,
        "cost": 0
      },
      {
        "day": "2024-05-24",
        "forecast": 238500,
        "actual": 212500,
        "hours": 36,
        "cost": 0
      }
    ]
  }
}

Import Sales Data

Import sales data in bulk using CSV format. This endpoint allows you to upload historical or forecasted sales data for multiple days and locations at once.

Mutation Parameters:

Parameter Type Required Description
data String! Yes CSV-formatted string containing sales data
columns [String!]! Yes Array of column names defining the structure of the CSV data
hourly Boolean! Yes Whether the data is hourly (true) or daily (false)

CSV Column Options:

The columns array should contain the following values in the order they appear in your CSV:

  • date - Date (format: YYYY-MM-DD or YYYY-MM-DD HH:MM AM/PM)
  • location - Location ID
  • forecast - Forecasted sales amount (in cents)
  • actual - Actual sales amount (in cents)
  • hours - Budgeted hours
  • cost - Budgeted cost (in cents)
  • forecast_units - Forecasted units sold
  • actual_units - Actual units sold

Response Fields:

Field Description
completed Whether the import completed successfully (true/false)
message Success or error message describing the result
errors Array of error messages if any rows failed to import

Implementation Notes:

  • The CSV data can include multiple locations by specifying the location ID in each row
  • The first row of the CSV should contain column headers (will be ignored)
  • Sales amounts should be provided in cents (e.g., 1000 = $10.00)
  • The hourly parameter determines if data is aggregated by hour or day
  • If any rows contain errors, they will be listed in the errors array
  • The import will process as many valid rows as possible, even if some rows fail
  • Duplicate entries for the same date/location will update existing records
  • All monetary values should be integers (cents, not dollars)

GraphQL Mutation

mutation ImportSalesData($data: String!, $columns: [String!]!, $hourly: Boolean!) {
  importSalesData(data: $data, columns: $columns, hourly: $hourly) {
    completed
    message
    errors
  }
}

Example Variables

{
  "data": "Date (eg. 2018-08-22 or 2018-08-22 09:00 am),Location ID,Forecast Sale,Actual Sale,Budget Hours,Budget Cost,Forecast Units,Actual Units\r\n2024-05-15,12325,1350,1480,0,0,10,12\r\n2024-05-16,12325,1270,1320,0,0,13,12\r\n2024-05-17,12325,1500,1460,0,0,20,30\r\n2024-05-18,12325,1760,1750,0,0,12,10\r\n2024-05-19,12325,1900,2400,0,0,30,30\r\n",
  "columns": ["date", "location", "forecast", "actual", "hours", "cost", "forecast_units", "actual_units"],
  "hourly": false
}

Example Response

{
  "data": {
    "importSalesData": {
      "completed": true,
      "message": "Data imported successfully.",
      "errors": []
    }
  }
}

Update Sales Data

Update existing sales data records. This endpoint allows you to modify forecast and actual sales figures, hours, and costs for specific days.

Mutation Parameters:

Parameter Type Required Description
input [UpdateSalesDataInput!]! Yes Array of sales data updates
input[].day String! Yes Date to update (YYYY-MM-DD format)
input[].forecast Int No Forecasted sales amount (in cents)
input[].actual Int No Actual sales amount (in cents)
input[].hours Int No Budgeted hours for the day
input[].cost Int No Budgeted cost for the day (in cents)

Response Fields:

Field Description
id Unique identifier for the updated sales record

Implementation Notes:

  • The location is determined by the X-Location-ID header
  • You can update multiple days in a single request by providing an array of inputs
  • Only the fields you provide will be updated; omitted fields retain their current values
  • Sales amounts and costs are in cents (divide by 100 to get dollar amounts)
  • The date must match an existing sales data record for the location
  • If the date doesn't exist, the record will be created with the provided values
  • All monetary values should be integers (cents, not dollars)

GraphQL Mutation

mutation UpdateSalesData($input: [UpdateSalesDataInput!]!) {
  updateSalesData(input: $input) {
    id
  }
}

Example Variables

{
  "input": [
    {
      "day": "2024-05-20",
      "forecast": 1700,
      "actual": 1650,
      "cost": 0,
      "hours": 24
    },
    {
      "day": "2024-05-21",
      "forecast": 1650,
      "actual": 1755,
      "cost": 0,
      "hours": 28
    },
    {
      "day": "2024-05-22",
      "forecast": 1200,
      "actual": 1450,
      "cost": 0,
      "hours": 24
    },
    {
      "day": "2024-05-23",
      "forecast": 1950,
      "actual": 1765,
      "cost": 0,
      "hours": 29
    },
    {
      "day": "2024-05-24",
      "forecast": 2385,
      "actual": 2125,
      "cost": 0,
      "hours": 36
    }
  ]
}

Example Response

{
  "data": {
    "updateSalesData": [
      {
        "id": "1582"
      },
      {
        "id": "1583"
      },
      {
        "id": "1584"
      },
      {
        "id": "1585"
      },
      {
        "id": "1586"
      }
    ]
  }
}