> For the complete documentation index, see [llms.txt](https://quant-reports.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quant-reports.gitbook.io/docs/data/returns/upload-custom-returns.md).

# Upload Custom Returns

Manually upload returns that not on the part of the automated workflow.

Upload custom return provide a feature to add your own monthly returns from **Report Platform**. Our system will automatically ingest and summarise the uploaded returns.

## Get Started

Before you begin, please make sure you follow the guideline to fill out the returns. We provide both **Long** and **Wide** format in a Excel file (.xlsx). You can read the details about each format below.

#### Long format

In the **Long** format, each row represents a **single model’s return for a single date**.

**Structure:**

* **model\_code** – required, must match the registered model code on Portfolio (e.g., `ALPHAFUND`).
* **date** – required, must be month-end (`YYYY-MM-DD`).
* **returns** – the monthly return value for that model/date in percentage format, i.e 1.5% or 0.015

{% hint style="success" %}
Best when your system already exports data in a transaction-style format.
{% endhint %}

{% hint style="warning" %}
Ensure all rows include both **model\_code** and **date**.
{% endhint %}

**Example:**

| model\_code | date       | returns |
| ----------- | ---------- | ------- |
| ALPHAFUND   | 2023-01-31 | -0.0234 |
| ALPHAFUND   | 2023-02-28 | -0.0831 |
| BETAFUND    | 2023-01-31 | 0.0768  |
| GAMMAFUND   | 2023-01-31 | -0.0783 |

#### Wide format

In the **Wide** format, each fund or portfolio is represented as a **separate column**, with the `date` column on the left.

**Structure:**

* **date** – required, must be month-end dates (`YYYY-MM-DD`).
* **One column per fund/model** – header names must match the model codes (e.g., `ALPHAFUND`, `BETAFUND`).
* **Cell values** – monthly returns for that date and fund.

{% hint style="success" %}
Best when you have multiple models side-by-side in Excel.
{% endhint %}

{% hint style="warning" %}
Ensure column headers match exactly with registered **model codes**.
{% endhint %}

| date       | ALPHAFUND | BETAFUND | GAMMAFUND |
| ---------- | --------- | -------- | --------- |
| 2023-01-31 | 0.0277    | -0.0925  | 0.0018    |
| 2023-02-28 | -0.0675   | 0.0033   | -0.0743   |

{% hint style="info" %}

### Which Should I Use?

**Wide** format is faster for bulk uploads from Excel sheets where portfolios are already in columns, while **Long** format is better for structured exports from databases or systems where each observation is row-based.

The platform accepts both formats — choose whichever fits your workflow.
{% endhint %}

## Uploading Returns

<figure><img src="https://2089370077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIVABW7U2wo08X8fhMX9L%2Fuploads%2FNoMFdTe98SmlWDWrYTkq%2FScreenshot%202025-09-30%20at%2012.48.55.png?alt=media&amp;token=d05005f8-c6f1-4cd8-a6a9-31004e1e1422" alt=""><figcaption></figcaption></figure>

Once you're ready with your data, proceed to the **Custom Returns Upload** section, pick your prepared file and click **Upload Excel**. Our system will validates your input and give feedback if it found any invalid or misconfigured data.

The system will also ask a confirmation about the result before being ingested to our data warehouse.

If everything is set, click on the Continue button. Or if you need to change something, click on the Change Field Submission button to upload the changes.