# Export configuration

This topic describes how to configure data exports using the Rebilly API.

## Date ranges

Use date ranges to limit the export data to a set time frame.
Always set a date range for a data export.
This keeps the data current and the export quick.

### Relative date range examples

Export data from yesterday:

```yaml
'dateRange': { 'start': 'yesterday', 'end': 'today' }
```

Export data from the previous month:

```yaml
'dateRange': { 'start': 'first day of last month midnight', 'end': 'first day of this month midnight' }
```

Export data from the last three days, starting at midnight:

```yaml
'dateRange': { 'start': '3 days ago midnight', 'end': 'now' }
```

Additional valid date inputs:

- `yesterday`
- `midnight`
- `today`
- `now`
- `noon`
- `tomorrow`
- `back of`
- `front of`
- `first day of`
- `last day of`
- `ago`
- `dayname`


### Absolute date range examples

Do not use absolute date ranges to create a recurring schedule for a data export.
An absolute range exports the same data each period.

For a `start` or `end` date in absolute format, use the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

From `2018-01-21` at `15:15:15` until now:

This example combines absolute and relative dates.

```yaml
'dateRange': { 'start': '2018-01-21T15:15:15Z', 'end': 'now' }
```

From `2018-01-21` at `15:15:15` until `2018-02-21` at `15:15:15`:

This example uses two absolute dates.

```yaml
'dateRange': { 'start': '2018-01-21T15:15:15Z', 'end': '2018-02-21T15:15:15Z' }
```

### Date range field example

By default, the date range applies to the time a transaction is processed.
To select another field, use the `field` attribute.
This example applies a date range filter to the time a transaction is created.

For more information, see [Fields](#fields).

```yaml
'dateRange': { 'start': 'yesterday', 'end': 'today', 'field': 'createdTime' }
```

## Fields

Use fields to specify the data to export in your request.

```yaml
'fields': ['id', 'email', 'firstName', 'lastName', 'createdTime', 'averageValue/amount']
```

### Export embedded fields

To export fields from embedded resources in the `detailed-csv` format, prefix the resource name and field name with `_embedded`.
Separate the prefix, resource name, and field name with a forward slash (`/`).

```yaml
'fields': ['id', '_embedded/customer/firstName', '_embedded/customer/email']
```

### Use wildcards in detailed-csv exports

Some fields hold an array of objects, also known as a list.
In the `detailed-csv` format, use the asterisk wildcard (`*`) to extract data from those fields.

- **Export items as JSON:** Append `/*` to the field path.
Each item in the array becomes a JSON object in one cell.
Commas separate the items.

```yaml
'fields': ['billingAddress/phoneNumbers/*']
```
Example output: `{"label":"work","primary":true,"value":"+123456789"}`
- **Export specific values from an array:** Append `/*/<propertyName>` to the field path.
Commas join the extracted values in one cell.

```yaml
'fields': ['billingAddress/phoneNumbers/*/value']
```
Example output: `+123456789`


If you need a field that is not available in Rebilly, create your own [Custom fields](/catalog/all/custom-fields).

## Arguments

Use arguments to filter, search, and sort the data in your export request.

For more information on filters, see [Search filters](/docs/dev-docs/search-filters).

```yaml
'arguments': { 'filter': 'string', 'sort': 'string', 'q': 'string' }
```

Filter by approved:

```yaml
'arguments': { 'filter': 'result:approved' }
```

Filter voids and refunds:

To filter by multiple values for the same field, separate filter names using a comma.

```yaml
'arguments': { 'filter': 'type:void,refund' }
```

Filter approved voids and refunds:

To filter by multiple values on more than one field, separate filter names using a semicolon.
For more information, see [Compound filters](/docs/dev-docs/search-filters#compound-filters).

```yaml
'arguments': { 'filter': 'result:approved;type:void,refund' }
```

## Limits

Each data export supports a maximum of 10,000,000 records.

When you create or modify a data export, records that match the request are counted.
If the count exceeds the limit, the request fails with a `422 Unprocessable Entity` response.
The export is not created or changed.
The response includes an error with a `type` of `data-export-limit-exceeded`, the number of matching records in `matchedRecords`, and the maximum in `maxRecords`.
To stay within this limit, add a date range or more filters.
Another option is to split the data into several smaller exports.

Recurring exports are checked each time they run because the record count changes between runs.
If a run exceeds the limit, that export does not complete.
Its `status` is set to `failed`, and `failureReason` is set to `record-limit-exceeded`.

Some failures are short-lived, so the export is retried a few times.
If the export still does not complete, its `status` is set to `failed` with a `failureReason` of `max-retries-reached`.

When an export is set to `failed`, an email is sent to each address in `emailNotification`.
The email includes the reason for the failure.
The `data-export-failed` webhook is also sent.
The payload contains the export and its `failureReason`.

Each output file contains up to 1,000,000 records.
This keeps every file within the row limit of most spreadsheet tools.
Exports that exceed this count are delivered as a single ZIP archive that contains numbered part files, such as `example-part1.csv` and `example-part2.csv`.
Each part file is valid on its own:

- `csv` and `detailed-csv` part files repeat the header row.
- `json` and `json-api` part files contain a complete array.
- `xml` part files contain their own root element.


`pdf` exports are always a ZIP archive that contains one PDF per record, and are never split into part files.