Export configuration

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

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.

Export data from yesterday:

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

Export data from the previous month:

'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:

'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

Do not use an absolute date range in 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 format.

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

This example combines absolute and relative dates.

'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.

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

By default, the date range applies to a time field that depends on the resource. For transactions, this is the processed time; for invoices, the issued time; for customers and orders, the created time. 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.

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

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

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

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 (/).

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

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.

  '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.

  'fields': ['billingAddress/phoneNumbers/*/value']
  

  Example output: +123456789

If you need a field that is not available in Rebilly, create your own Custom fields.

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

For more information on filters, see Search filters.

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

Filter by approved:

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

Filter voids and refunds:

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

'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.

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

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 error also contains 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 a maximum of 1,000,000 records. This keeps every file within the row limit of most spreadsheet tools. Exports that exceed this value are delivered as a single ZIP archive. The archive 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 with one PDF per record. These exports are never split into part files.