This is the endpoint-by-endpoint reference for the Segment Export Connector — for engineering teams at a Customer Engagement Platform (CEP) building the integration. For what this connector does and why a merchant would turn it on, read Segment Export Connector: Take Your Shopflo Segments to WhatsApp and CRM first.

Authentication

Every request needs an Authorization header carrying the CEP's Shopflo API key, in the form sfat-<api_key> — the gateway validates it on every call. PUT requests also need Content-Type: application/json.

1. List Segments

Purpose: returns the merchant's available segments, so the CEP can let a user pick which one to sync or export.

Request

GET http://api.shopflo.co/shorts/api/v1/connector/segments

Headers

Header	Type	Required	Description
Authorization	string	Yes	CEP's Shopflo API key, validated by the gateway.

Response body

Param	Type	Description
`success`	boolean	Whether the call succeeded.
`data`	array	List of segment objects.
`data[].segment_id`	string (UUID)	Unique identifier of the segment.
`data[].name`	string	Display name of the segment.
`data[].description`	string	Description of the segment's audience criteria.
`data[].status`	string	Segment status — `ACTIVE`, `INPROGRESS`, or `FAILED`.
`data[].created_at`	string	Timestamp the segment was created.
`data[].updated_at`	string	Timestamp the segment was last updated.
`current_page`	number	Current page index (0-based).
`page_size`	number	Records per page (max 100).
`max_pages`	number	Total pages available.
`total_count`	number	Total number of segments.

Sample response

{
  "success": true,
  "data": [
    {
      "segment_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "name": "3+ Orders — WhatsApp Winback",
      "description": "Customers with 3 or more completed orders",
      "status": "ACTIVE",
      "created_at": "2026-08-01T10:00:00Z",
      "updated_at": "2026-08-10T10:00:00Z"
    }
  ],
  "current_page": 0,
  "page_size": 100,
  "max_pages": 1,
  "total_count": 1
}

2. Get Segment Data (trigger an export)

Purpose: kicks off an async job that produces a CSV of the segment's data, and returns a report_id used to poll progress via the Report Status API.

Request

POST http://api.shopflo.co/shorts/api/v1/connector/segments/{segment_id}/export

Path parameter

Param	Type	Required	Description
`segment_id`	string (UUID)	Yes	The segment to export, obtained from List Segments.

Headers

Header	Type	Required	Description
Authorization	string	Yes	CEP's Shopflo API key, validated by the gateway.

Response body

Param	Type	Description
`success`	boolean	Whether the call succeeded.
`data.message`	string	Status message, e.g. "Report download started successfully".
`data.report_id`	string (UUID)	ID of the export job; pass this to the Report Status API to poll for completion.

Sample response

{
  "success": true,
  "data": {
    "message": "Report download started successfully",
    "report_id": "9c858901-8a57-4791-81fe-4c455b099bc9"
  }
}

3. Report Status

Purpose: polls the status of an export job created by Get Segment Data. Once status is COMPLETED, the response includes a presigned URL to download the exported CSV.

Request

GET http://api.shopflo.co/shorts/api/v1/connector/segments/export/status/{report_id}

Path parameter

Param	Type	Required	Description
`report_id`	string (UUID)	Yes	Returned by Get Segment Data.

Headers

Header	Type	Required	Description
Authorization	string	Yes	CEP's Shopflo API key, validated by the gateway.

Response body

Param	Type	Description
`success`	boolean	Whether the call succeeded.
`data.report_id`	string (UUID)	The export job ID.
`data.status`	string	Job status: `PROCESSING`, `COMPLETED`, `NO_DATA` (export ran but found no matching records), or `FAILED`. Each transition fires a corresponding webhook event — see Webhook Events below.
`data.file_size`	number	Size of the exported file, in bytes.
`data.url`	string	Presigned S3 URL to download the CSV. Time-limited — download promptly once you get it.

Sample response

{
  "success": true,
  "data": {
    "report_id": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "status": "COMPLETED",
    "file_size": 48213,
    "url": "https://shopflo-exports.s3.amazonaws.com/..."
  }
}

Webhooks

Rather than poll Report Status, configure a webhook once and Shopflo will push a notification to your endpoint on every status change of an export job.

Setup Webhooks

Purpose: configures (creates/updates) the webhook subscription for a merchant, so Shopflo can push event notifications (e.g. on segment_export completion) to the CEP's endpoint.

Request

PUT http://api.shopflo.co/shorts/api/v1/connector/segments/config

Request body

Param	Type	Required	Description
`enabled`	boolean	Yes	Master switch for webhooks on this merchant.
`webhooks`	array	Yes	List of webhook configs.
`webhooks[].raw`	boolean	No	Send the raw/unwrapped payload.
`webhooks[].enabled`	boolean	Yes	Enable this specific webhook entry.
`webhooks[].url`	string	Yes	Destination URL to receive the webhook (the CEP's endpoint).
`webhooks[].event_names`	array of string	Yes	Events to subscribe to, e.g. `segment_export_completed`.
`webhooks[].headers`	object	No	Custom headers sent with each webhook call (e.g. a shared-secret header for verification).
`webhooks[].channels`	array of string	No	Delivery channels/targets.

Headers

Header	Type	Required	Description
Authorization	string	Yes	`sfat-<api_key>`
Content-Type	string	Yes	`application/json`

Sample request body

{
  "enabled": true,
  "webhooks": [
    {
      "raw": true,
      "enabled": true,
      "url": "https://cep.example.com/webhooks/shopflo-segments",
      "event_names": ["segment_export_completed", "segment_export_failed"],
      "headers": {
        "x-nv": true,
        "x-nv-security-magic": "<shared-secret>"
      },
      "channels": ["web"]
    }
  ]
}

Response body — echoes back the saved config:

Param	Type	Description
`success`	boolean	Whether the call succeeded.
`data.enabled`	boolean	Master switch for webhooks on this merchant.
`data.webhooks`	array	Same shape as the request's `webhooks` array, reflecting what was persisted.

Get Webhooks

Purpose: fetches the currently configured webhook settings for the merchant.

Request

GET http://api.shopflo.co/shorts/api/v1/connector/segments/config

Headers

Header	Type	Required	Description
Authorization	string	Yes	`sfat-<api_key>`

Response body: same shape as Setup Webhooks' response.

Webhook Events

event_names (in Setup Webhooks) supports the following events, each tied to a report status transition on the underlying export job:

Event	Fired when
`segment_export_started`	status becomes `PROCESSING`
`segment_export_completed`	status becomes `COMPLETED`
`segment_export_no_data`	status becomes `NO_DATA` (export ran, no matching records)
`segment_export_failed`	status becomes `FAILED`

→ Segment Export Connector: Take Your Shopflo Segments to WhatsApp and CRM — what this connector does and why a merchant would turn it on

Need help? Reach out to us at support@shopflo.com and we'll be happy to assist.

Segment Export Connector: Take Your Shopflo Segments to WhatsApp and CRM

Segment Export Connector — API & Webhooks Reference

Authentication

1. List Segments

2. Get Segment Data (trigger an export)

3. Report Status

Webhooks

Setup Webhooks

Get Webhooks

Webhook Events

Related Articles