Skip to main content

Exporting data from Spaaza

Contents​

Overview​

Spaaza provides an asynchronous, task-based export system that lets you extract data from the platform in CSV or JSON format. This is the recommended approach for programmatic or large-volume data exports.

Exports are managed through the Tasks API. You create a task describing what to export, wait for it to complete, and download the resulting file. For full endpoint documentation including parameters, authentication, response schemas, and error codes, see the Tasks API reference.

What you can export​

Export indexDescription
transactionsBasket/transaction records including item-level data
usersCustomer/user accounts and profile information
vouchersIssued vouchers, including status and redemption data
wallet-ledgerWallet credit and debit entries
productsProduct catalog records
product-variantsProduct variant records

Export formats​

FormatDescription
csvComma-separated values file. Recommended for most use cases.
jsonJSON file containing all records. Can be very large for high-volume exports.

Workflow overview​

The following Mermaid sequence diagram shows the typical export workflow. The client creates a task, polls its status until completion, and then downloads the result file from temporary storage.

sequenceDiagram
    participant Client
    participant Services API
    participant Storage

    Client->>Services API: POST /tasks (create export)
    Services API-->>Client: Task ID + state: READY
    loop Poll until DONE
        Client->>Services API: GET /tasks/{id}
        Services API-->>Client: state: INPROGRESS / DONE
    end
    Client->>Services API: GET /tasks/{id}/download_url
    Services API-->>Client: Temporary download URL
    Client->>Storage: GET (download file)
    Storage-->>Client: CSV/JSON file

Quick start example​

Create a simple CSV export of all users:

curl -X POST 'https://{Services API hostname}/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_ID:ACCESS_TOKEN_SECRET' \
  -d '{
    "chain": YOUR_CHAIN_ID,
    "desc": "Full user export",
    "target": {
      "action": "export",
      "export_index": "users",
      "export_format": "csv"
    },
    "trigger": {
      "once": "2026-05-26T12:00:00Z"
    }
  }'

Set trigger.once to a time shortly in the future when you want the export to run.

For authentication details, see Permissions and Authentication in the Tasks API reference.

Filtering exports with segments​

You can filter an export to include only records matching specific criteria by adding a segment object to the trigger field. For example, to export only vouchers redeemed in the last 7 days:

"trigger": {
  "once": "2026-05-26T12:00:00Z",
  "segment": {
    "entity": "people",
    "index": "vouchers",
    "join": "all",
    "chain_id": YOUR_CHAIN_ID,
    "rules": [
      {
        "field_name": "date_time_redeemed",
        "field_type": "date",
        "operator": "relative_less_than",
        "time_factor": "day",
        "time_amount": 7
      }
    ]
  }
}

Alternatively, if you have an existing saved segment in Console, you can reference it by ID:

"trigger": {
  "once": "2026-05-26T12:00:00Z",
  "segment_id": "YOUR_SEGMENT_ID"
}

You can find the segment ID from the URL in Console when viewing a particular segment.

See the Segment filter reference for the full list of operators, field types, and advanced filtering options.

Recurring exports​

Tasks can be set to repeat on a schedule by adding trigger.repeat. After each run, the task automatically reschedules itself:

"trigger": {
  "once": "2026-05-26T00:00:00Z",
  "repeat": "daily",
  "segment": {
    "entity": "people",
    "index": "transactions",
    "join": "all",
    "chain_id": YOUR_CHAIN_ID,
    "rules": [
      {
        "field_name": "timestamp",
        "field_type": "date",
        "operator": "relative_less_than",
        "time_factor": "day",
        "time_amount": 1
      }
    ]
  }
}

Supported repeat values: "daily", "weekly", "monthly". See Scheduling and triggers in the Tasks API reference for details.

Best practices​

  • Stagger task scheduling: If you need to run multiple exports, spread them across different trigger.once times rather than scheduling them all at the same moment. This avoids overloading the task runner and ensures each export completes promptly.
  • Prefer CSV for large exports: JSON exports can produce very large files. CSV is generally more efficient for bulk data transfer.
  • Use segment filters for incremental syncs: Rather than exporting all data each time, use relative date filters (e.g. relative_less_than with time_factor: "day" and time_amount: 1) to export only records from the last 24 hours.
  • Chunk large historical exports: If a full export times out, break it into bounded date windows using is_between_date with start_date and end_date (e.g. one month at a time). See Exporting transactions for a detailed example.
  • Poll with reasonable intervals: Check task status every 10–30 seconds. Very large exports may take several minutes to complete.
  • Download promptly: The download URL is temporary (valid for approximately one hour). Download the file shortly after requesting the URL.

Export guides​