How Can I Access Sales Incentive Data Using API Calls?

How Can I Access Sales Incentive Data Using API Calls?


You can use the OData protocol to access sales incentive data in a read-only manner. To learn about the OData V4 API standard, refer to this article.

Your API Key and associated OData URL enable you to programmatically retrieve plans, calculations, credits, rewards, transactions, teams, users, etc.

Here are the steps to retrieve your OData URL:
  • Login to your workspace
  • On the left pane, click on "My Account > My Profile"
  • Click on the "Security" tab (if needed)
  • Click on the "copy" action under "API Key"

To visually explore the API:
  • Login to your workspace
  • On the left pane, click on "Settings > Connections > OData API"
  • Alternatively, you can connect using a BI tool such as Microsoft Power BI to access entities 

In this example, we selected the Calculation entity. We can see different examples showing how to retrieve data.



Scrolling down on the same page, we can see a list of references to other entities, as well as properties available on the Calculation entity.



Please note the following:
  • All OData access is read-only
  • Only workspace full admins can query workspace data using OData
  • You can discover the entire schema using OData
  • Excessive data request will result in HTTP 429 throttling responses 
  • Please contact our support team if you need to revoke key access

The following entities are available via OData. We encourage you to use the API explorer mentioned above to better understand the schema and relationships. 
  • Alert - Alerts track issues within your workspace.
  • Announcement - Announcements track messages within incentive dashboards, as well as workspace-level notes.
  • Calculation - Calculations determine commission payouts for one specific plan (ex: Quarterly Bonus) and period (ex: Q4).
  • CalculationCommission - Calculation commissions track per-transaction payouts. Calculation commissions cannot track payouts which are not per-transaction (ex: cash bonuses).
  • CalculationCredit - Calculation credits track which transactions were credited to which users / teams. Calculation credits are also used to determine attainment.
  • CalculationResult - Calculation results summarize payouts per payee. Calculation results do not track commissions at the transaction level.
  • CutomVariable - Custom variables are time-dependent values which can be set on entities such as users, teams, or plans.
  • EventLog - Event log entries track activity within each workspace.
  • Plan - Plans represent commission structures. Each plan has a set of eligibility, crediting, attainment, and payout rules.
  • PlanEnrollment - Plan enrollments track which users have completed the enrollment process.
  • PlanRole - Plan roles track plan-level permissions granted to users over specific plans.
  • Report - Reports track published reports.
  • Survey - Surveys track individual surveys shown on incentive dashboards.
  • SurveyResult - Survey results track individual responses to surveys.
  • SystemUser - System users are users within your workspace (ex: full admins, limited admins, participants, etc.).
  • Team - Teams can be used to grant permissions or to perform rollups.
  • TeamAlias - Team aliases are used to credit sales events to teams. Team aliases can be territory names, regions, team IDs, etc.
  • TeamMember - Team members track which users are members of which teams.
  • Transaction - Transactions represent commissionable events (ex: opportunities, orders, invoices, payments, etc.).
  • UserAlias - User aliases are used to credit sales events to users. User aliases can be user names, email addresses, employee IDs, etc.
  • WorkspaceRole - Workspace roles describe user access levels and user preferences within a workspace.
  • WorkspaceSetting - Workspace settings track workspace-level options.
  • CatalogEntry - Catalog entries track individual entries within the product catalog.

Here is a partial overview of the schema and relationships, focusing on calculation-related entities:



    • Related Articles

    • How Can I View A Report's Raw Data?

      To view a report's raw data, click on the following icon when viewing a report: You can also access raw data via OData or Power BI (learn more)

    • How Can I Create A Power BI Report?

      Using Power BI, you can generate complex sales incentive reports - including drill-downs, multi-level grouping, advanced visualizations, enterprise report publishing, and much more. You can also create reports by typing natural language queries. To ...

    • What Is A Plan Snapshot?

      When you submit a sales incentive plan for calculation, we take a snapshot of your plan at the time the calculation was started. The benefits are: The calculation is not affected by changes made to the plan while the calculation is occurring You have ...

    • How Are Currencies Handled?

      Sales Cookie in designed to handle currencies in every aspect of your sales incentive program including: Converting between different currencies found in various sales transactions Assigning rewards to users based on their own currency settings ...

    • What Reports Are Available?

      Sales Cookie offers different types of reports: Payout reports Credit reports Attainment reports Power BI reports For each report, you can filter data: By time period By all plans vs. a specific plan By all calculations vs. a specific calculation By ...