Orders

export_orders

destructive write

Export orders

Copy page

Send the merchant a spreadsheet of the Store orders in a date range, in the same CSV format the merchant admin export uses.

Overview

Queues a CSV export of the Store orders created in an inclusive UTC date range, and emails a download link to the Store contact email. The recipient is always the Store contact email and cannot be changed. The range may include at most 366 days and 1,000 orders, and its estimated CSV size must stay within the export limit. The export changes no order. The CSV contains shopper names and addresses, and an email that has been sent cannot be recalled, so the call needs confirm: true and an idempotency_key that makes an exact repeat replay the original response without a second email. Each connection can queue three exports in ten minutes. It requires the orders:write scope.

Permission

Requires theorders:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHinttrue

Prerequisites

The store contact email must be set in the merchant admin, because the export is emailed there.
A merchant has connected this store and approved the orders:write scope.

Side effects

Queues one export job, which writes the CSV to storage and emails a download link to the store contact email.
The email cannot be recalled, and the CSV contains shopper personal data.
Changes no order.
Uses one of the three exports this connection may queue in ten minutes. A replay uses none.
Claims the idempotency_key for at least 24 hours.

Arguments

created_fromstringrequired

The first included UTC order creation date, in YYYY-MM-DD format.

created_tostringrequired

The last included UTC order creation date, in YYYY-MM-DD format. It must be on or after created_from, and the range may include at most 366 days.

confirmbooleanrequired

Must be true to apply the change, because the export emails a CSV of shopper data to the store contact email, and an email that has been sent cannot be recalled. Without it the call returns a confirmation_required error and changes nothing.

idempotency_keystringrequired

A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict.

Result

The queued export: its status, the date range, and the email address the link goes to. The CSV itself is not returned; it arrives by email when the job finishes.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

exportobjectalways present

export.statusstringalways present

Always queued: the CSV is built and emailed later.

One of: queued

export.recipient_emailstringalways present

The store contact email the download link goes to.

export.created_fromstringalways present

export.created_tostringalways present

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

Error cases

confirmation_required

Send confirm: true. The export email cannot be recalled.

export_too_large

The range contains more than 1,000 orders or too much CSV data. Choose a shorter range.

idempotency_key_conflict

That key was used with different arguments. Re-send the original arguments or issue a new key.

insufficient_scope

The connection was approved without orders:write.

invalid_field

A date is not YYYY-MM-DD, created_to is before created_from, or the range is longer than 366 days. Correct the field each errors entry names in parameter.

missing_store_contact_email

The store contact email is not set. It has to be completed in the merchant admin before an export can be sent.

rate_limited

This connection has queued three exports in the last ten minutes. Wait retry_after seconds.

Email the July orders

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "export_orders",
    "arguments": {
      "created_from": "2026-07-01",
      "created_to": "2026-07-31",
      "confirm": true,
      "idempotency_key": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "export": {
        "status": "queued",
        "recipient_email": "orders@example.com",
        "created_from": "2026-07-01",
        "created_to": "2026-07-31"
      },
      "idempotent_replay": false
    }
  }
}

Without confirmation nothing is queued and no email is sent (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "export_orders",
    "arguments": {
      "created_from": "2026-07-01",
      "created_to": "2026-07-31",
      "confirm": false,
      "idempotency_key": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Exporting the orders created from 2026-07-01 to 2026-07-31 emails a CSV of shopper data to the store contact email, and an email that has been sent cannot be recalled.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}