Skip to main content
Skip table of contents

Cinnamon Data Interface - Returns

Key Principles


Decision / Discussion

Flexible aggregation over time

  • The reporting engine should be flexible to aggregate (cumulate) returns over time

Scope one Portfolio

  • the inteface should always deliver data on the scope of a single portfolio (or consolidation)

Benchmark Data

  • Benchmark data should be included

  • No returns should be delivered if there is only benchmark-data (see below about gaps)


  • The standard return data granularity is monthly (optionally/additionally deliver daily data) so we can assure to show the correct monthly returns

Calendar Days

  • the field "day" is referring to a calendar day, e.g. day 5 in month 1 in year 2018 is referring to January 5th 2018.

Period Definitions

  • Periods are defined by start and end dates

  • The semantics of the start date is BOD (00:00:00) while the end date means EOD (23:59:59)

Return Types

  • Gross: return without portfolio level fees (but including transaction fees)

  • Net: return including portfolio level fees

  • BM: return of the benchmark

  • Other return types (secondary benchmark, other flavours of fee recognition)

Completeness &

  • Daily return data can have gaps (e.g. weekends) but there should be no daily return entry without both gross/net values.

  • Monthly data have are interpreted to be valid for the calendar ultimo of the month

  • Daily data does not have to be artificially completed with a month end record (so March 31st can be missing in daily if this was a weekend)

  • If an order requests data for a period before the performanceMeasurementStartDate) no valid response should be returned

  • If an order requests data for a period reaching into the future (with respect to the most current data available) no valid response should be returned

  • As the end of the performance history of a portfolio is (currently) not defined in masterdata, all month till the endDate are expected to be contained in the response

Incomplete month periods

  • If a portfolio starts it's performance history in the middle of a month, the initial index value is interpreted for the performanceMeasurementStartDate

  • If the endDate of a request lies in the middle of a month, the last daily index value previous to the endDate is interpreted (the endDate can be missing in the daily records)

Interface "PortfolioReturns"

Usage & Contents

  • Query performance / return data on portfolio level for a given period used to produce

    • PO001: Performance Overview - reporting frequency & YTD

    • PO005: Performance Overivew - rolling

    • PO003: Cumulated performance chart

    • etc.

  • contains monthly (and optionally daily) returns

    • for portfolio and benchmark

    • for all available return types (gross, net, ?)

Reporting Business Logic

  • cumulation over time (monthly → quarterly, YTD, ITD etc.) or rather de-cumulating index values to monhtly / quarterly returns

  • alignment of data frequencies (monthly ITD history with daily for more current periods)

  • relative return calculation for different return types

  • formatting of returns (in %, in bps)

Consistency Rules

The following rules should be adhered to by any response and will be checked when consuming a response:

  • All data returned has to respect the requested period: no data earlier than startDate, no (daily) data later than endDate

  • No gaps are allowed in the years and months arrays (only daily array can have gaps for weekends/holidays)

  • (Year, Month, Day) has to be a valid date (e.g. no 31. of april)

  • all return data (years, months, days) should be sorted in the chronological order

  • if ordered with "includeBenchmark", "bmIndexStart" has to be provided and all indexed return objects have to provide a "bmIndex" value

  • the interface should respond with a valid file for any period starting earliest at PortfolioMasterData.performanceMeasurementStartDate and ending with the most current date (delivered by future data availability calls)

  • if ordered with "includeDailyReturns" all and only the months buckets beginning with the month of PortfolioMasterData.dailyPerformanceStartDate to the endDate should provide daily return data.






The id of the portfolio (or consolidation) in the data source


string (date)

The start date of the period for which return data is requested


string (date)

The end date of the period for which return data is requested


boolean (default: false)

Response to include daily return data (where available)


boolean (default: false)

Response to include benchmark return data



parameter to query data of the portfolio measured against another benchmark

Example call






Interface "InstrumentReturns"

Usage & Contents

  • used to produce instrument returns tables and charts (MA001, MA003, MA004)

Reporting Business Logic

Consistency rules

  • Same consistency rules as for PortfolioReturns





string (date)

The start date the reporting is produced for


string (date)

The end date the reporting is produced for



The list of instruments the return series should be generated


boolean (default: false)

Response to include daily return data (where available)

Example call






JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.