> For the complete documentation index, see [llms.txt](https://knowledgebase.flaik.com/flaik-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/incentives-by-date-range.md). # Incentives by Date Range Returns staff incentives and commissions for a date range, at **one row per timesheet entry per incentive component**. Base activity wages are not included - those come from [Wages by Date Range](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/wages-by-date-range). There is **no server-side aggregation**. The per-component grain is deliberate: it is the only grain from which every resort's payroll policy can derive its own totals. This is a read-only reporting feed; nothing is written. {% hint style="info" %} **This is an alternative to, not a replacement for,** [**Paid Activities by Date Range**](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/paid-activities-by-date-range)**.** That combined feed remains fully supported and is in production use. Use Wages + Incentives if you want the two components separated; use Paid Activities if you want them together. Do not pull both for the same period - you will double-count. {% endhint %} ### Authentication ```http Authorization: Bearer {access_token} ``` ### Endpoint ```http GET {api-url}/api/timekeeping/incentives ``` #### Query parameters | Parameter | Type | Description | | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `startDate` | date | **Required.** Start of the range (`YYYY-MM-DD`). | | `endDate` | date | **Required.** End of the range (`YYYY-MM-DD`). | | `updatedAfterLocalDateTime` | date-time | **Required.** Only entries updated after this time. Interpreted in **resort-local time**, not UTC - convert using the `timezone` from [Resort Details](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/global-settings/resort-details). | | `seasonId` | integer | **Required.** The season to report on. | | `includeResolutionStatus` | boolean | Optional, defaults to `false`. Opt in to the `resolutionStatus` field - see below. | ### Response `200` with an array of incentive rows. Each row carries the same employee and entry context as the wage feed: `seasonId`, `seasonName`, `payrollId`, `employeeIdentifier`, `employeeName`, `flaikEmployeeId`, `timesheetId`, `timesheetStatus`, `timesheetDate`, `startTime`, `endTime`, `paidActivityGroupId`, `paidActivityGroupName`, `paidActivityId`, `paidActivityName`, `paidActivityType`. The incentive-specific fields: | Field | Type | Description | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `type` | string | `"staffIncentive"` or `"commission"`. Unknown sections pass through with their raw section name rather than being dropped. | | `sourceKey` | string? | Raw key of the component. `null` on unparseable rows. | | `incentiveId` / `incentiveName` | integer? / string? | The incentive, when resolved | | `amount` | decimal | The incentive or commission amount | | `minutes` | integer | Minutes attributed to this component | | `guestCount` | integer? | **Commission only** - `null` on staff-incentive rows | | `guestDetails` | string? | Commission only | | `payCodeId` / `payCodeName` / `payCodeType` / `payCodeCostCentre` | | **The incentive's own resolved pay code** - not the parent activity's | | `businessStructureId` / `businessStructureName` / `costCentre` / `exportBusinessStructureName` / `externalId` / `locationName` / `parentPath` | | Resolved from the parent entry's paid activity | | `jobCodeId` / `jobCodeName` / `jobCodeType` / `jobCodeCostCentre` | | Resolved from the parent entry | | `isAutoAppliedToStaff` | boolean? | Whether the incentive is applied automatically | | `resolutionStatus` | string? | `null` unless `includeResolutionStatus=true` - see below | ### Rows are never dropped Set `includeResolutionStatus=true` to have each row explain why its component did or did not resolve: `resolved` · `hardcodedCommission` · `unknownSection` · `unknownIncentive` · `missingPayCode` · `unparseable` It is off by default so the feed is not treated as a configuration validator. **Rows are returned either way** - a component that failed to resolve is surfaced for review, never silently dropped. An `unparseable` row indicates corrupt incentive detail worth manual review. Turning it on for a first integration run is a good way to surface resort configuration gaps before you rely on the totals. ### The three timekeeping feeds | Feed | Grain | Contains | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | | [Paid Activities by Date Range](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/paid-activities-by-date-range) | per timesheet entry | wages and commission combined - supported, in production use | | [Wages by Date Range](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/wages-by-date-range) | per timesheet entry | base activity wage only | | **Incentives by Date Range** (this page) | per entry x incentive component | staff incentives and commissions | {% hint style="warning" %} **No entry-level join key back to the wage feed.** Incentive rows are self-contained - they carry their own employee, entry and cost-centre context precisely so they can be consumed without a join. One timesheet entry produces exactly one wage row but zero or many incentive rows, so the two feeds cannot be summed naively. {% endhint %} Need help? Contact . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/timekeeping/incentives-by-date-range.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.