> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> The list of available fields that can be included in a report for transactions.

The `transactions` model allows setting three parameters.

1. `fields`: a list of fields
2. `filters`: a dictionary of filters
3. `sort`: a list of sorting fields

## `fields`

Fields allow the selection of which columns to export in the report.

| Field |
| - |
| `id` |
| `external_identifier` |
| `status` |
| `created_at` |
| `updated_at` |
| `authorized_at` |
| `captured_at` |
| `voided_at` |
| `amount` |
| `currency` |
| `captured_amount` |
| `refunded_amount` |
| `method` |
| `scheme` |
| `payment_service_transaction_id` |
| `payment_service_id` |
| `payment_service_definition_id` |
| `payment_service_display_name` |
| `auth_response_code` |
| `raw_response_code` |
| `raw_response_description` |
| `metadata` |
| `is_subsequent_payment` |
| `merchant_initiated` |
| `payment_source` |
| `three_d_secure_status` |
| `three_d_secure_error_description` |
| `three_d_secure_eci` |
| `three_d_secure_auth_resp` |
| `three_d_secure_method` |
| `buyer_external_identifier` |
| `billing_details_first_name` |
| `billing_details_last_name` |
| `billing_details_email_address` |
| `billing_details_phone_number` |
| `billing_details_address_city` |
| `billing_details_address_country` |
| `billing_details_address_postal_code` |
| `billing_details_address_state` |
| `billing_details_address_state_code` |
| `billing_details_address_house_number_or_name` |
| `billing_details_address_line1` |
| `billing_details_address_line2` |
| `billing_details_address_organization` |
| `billing_details_tax_id` |
| `billing_details_tax_id_kind` |
| `authorized_amount` |
| `intent_outcome` |
| `gift_card_redemptions_amount` |
| `gift_card_redemption_refunds_amount` |
| `settled` |
| `settled_currency` |
| `settled_amount` |

<Note>
  **Amounts**

  Amount fields are integers in the smallest currency unit, the same as in the API. For example, `1299` in `USD` is \$12.99. Reports don't round or format amounts.

  To get the value in the major unit, divide by 10 raised to the number of decimal places the currency uses in ISO 4217. For example, divide `USD` amounts by 100. `JPY` has no decimal places, so `JPY` amounts need no conversion. Convert `settled_amount` using `settled_currency`.
</Note>

<Tip>
  **All fields**

  If all fields should be included in a report, just set `fields` as `null`
</Tip>

## `filters`

Filters allow filtering of the transactions' data to be exported.

| Value | Type | Validation |
| - | - | - |
| `authorized_at` | `dict[str, str]` | See **Date-time filter** below for more details |
| `captured_at` | `dict[str, str]` | See **Date-time filter** below for more details |
| `created_at` | `dict[str, str]` | See **Date-time filter** below for more details |
| `currency` | `str` | Valid ISO 4217 currency code |
| `metadata` | `list[dict[str, str]]` | List of string-to-string dictionaries |
| `method` | `list[str]` | List of valid methods |
| `scheme` | `list[str]` | List of valid schemes |
| `status` | `list[str]` | This should be a list |
| `is_subsequent_payment` | `bool` | Boolean indicating transactions with subsequent payments |
| `merchant_initiated` | `bool` | Boolean indicating transactions initiated by the merchant |
| `payment_source` | `list[str]` | List of valid transaction sources |
| `three_d_secure_status` | `list[str]` | List of valid 3DS statuses |
| `three_d_secure_eci` | `list[str]` | This should be a list |
| `three_d_secure_auth_resp` | `list[str]` | This should be a list |
| `updated_at` | `dict[str, str]` | See **Date-time filter** below for more details |
| `voided_at` | `dict[str, str]` | See **Date-time filter** below for more details |

<Tip>
  **No filters**

  If no filters should be applied, just set `filters` as `null`
</Tip>

### Date-time filter

A date-time filter could be defined as follows.

```json theme={"system"}
{
    "start": str
    "end": str
}
```

`start` and `end` allow three types of values:

1. Valid ISO 8601 timestamp with or without timezone. UTC is assumed if the time zone is not specified.
2. Date-time placeholder to be set dynamically
3. `null`: this represents an open range

The available placeholders for dynamic timestamps are:

* `day_start`: replaced with the first instant of the day, for the period of time the execution is reading data from.
* `day_end`: replaced with the last instant of the day, for the period of time the execution is reading data from.
* `week_start`: replaced with the first instant of the week (for example Monday at 00:00), for the period of time the execution is reading data from.
* `week_end`: replaced with the last instant of the week (for example Sunday at 23:59), for the period of time the execution is reading data from.
* `month_start`: replaced with the first instant of the month, for the period of time the execution is reading data from.
* `month_end`: replaced with the last instant of the month, for the period of time the execution is reading data from.

#### Validations

The validations below are checked:

1. `start <= end`, only when both are timestamps
2. `start` and `end` cannot be null at the same time

## `sort`

The sort parameter allows selection of how to sort the data exported. This allows multiple columns to be used for sorting.

<Warning>
  Sorting is only applied if at least one date-time filter is present with a duration of 31 days or less.
</Warning>

A sort parameter should have the format:

```json theme={"system"}
{
    "field": str
    "order": str
}
```

`field` can be:

1. `authorized_at`
2. `captured_at`
3. `created_at`
4. `updated_at`
5. `voided_at`

`order` can be:

1. `asc`: ascending order
2. `desc`: descending order

<Tip>
  **No sorting**

  If no sorting should be applied, just set `sort` as `null`
</Tip>

## Example

Example of report creation using the `transactions` model.

```json theme={"system"}
{
  "name": "Test report",
  "spec": {
    "model": "transactions",
    "params": {
      "fields": ["id", "created_at"],
      "filters": {
        "status": ["capture_succeeded"],
        "created_at": {
          "start": "month_start",
          "end": "month_end"
        }
      },
      "sort": [
        {
          "field": "created_at",
          "order": "desc"
        }
      ]
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.