Data Imports

Endpoint

Bulk data imports from CSV files and external systems.

List data imports

GET

https://api.preo.dev

/v1/data-imports

List all data imports from accessible editions. By default, excludes cancelled imports unless include_cancelled=true is specified. Optionally filter by edition_id to see imports from a specific edition.

List data imports › query Parameters

created_after

string · date-time

created_before

string · date-time

edition_id

string | null

Optional: Filter by specific edition. If not provided, shows imports from all accessible editions.

include_cancelled

boolean

Include cancelled imports (default: false)

ordering

string[] · style: form

Ordering

created - Created
-created - Created (descending)
modified - Modified
-modified - Modified (descending)
stage - Stage
-stage - Stage (descending)

Enum values:

-created

-modified

-stage

created

modified

stage

page

integer

A page number within the paginated result set.

page_size

integer

Number of results to return per page (default: 100).

service

string

stage

string · enum

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

cancelled

completed

failed

importing

needs_column_mapping

needs_product_mapping

uploaded

List data imports › Responses

200

count

integer · required

object[] · required

next

string · uri

previous

string · uri

GET/v1/data-imports

curl --request GET \
  --url https://api.preo.dev/v1/data-imports

shell

Example Responses

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "id",
      "name": "name",
      "organization": {
        "id": "id",
        "name": "name",
        "slug": "slug",
        "avatar": {
          "thumbnail": "https://www.example.com/path/to/resource",
          "optimized": "https://www.example.com/path/to/resource",
          "large": "https://www.example.com/path/to/resource",
          "original": "https://www.example.com/path/to/resource"
        }
      },
      "edition": {
        "id": "id",
        "full_name": "full_name",
        "slug": "slug",
        "start_date": "2024-08-25T15:00:00Z",
        "end_date": "2024-08-25T15:00:00Z",
        "timezone": "timezone",
        "is_draft": true,
        "published_at": "2024-08-25T15:00:00Z"
      },
      "stage": "uploaded",
      "service": "shopify",
      "default_country_code": "default_country_code",
      "data_file_url": "data_file_url",
      "data_file_name": "data_file_name",
      "parsed_data": {
        "customers_total": 0,
        "customers_existing": 0,
        "products_total": 0,
        "products_existing": 0,
        "orders_total": 0,
        "orders_existing": 0
      },
      "product_mappings_complete": "product_mappings_complete",
      "created": "2024-08-25T15:00:00Z",
      "modified": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

Create data import

POST

https://api.preo.dev

/v1/data-imports

Upload file for import. Columns are extracted automatically and import transitions to needs_column_mapping stage.

Create data import › Request Body

Serializer for creating new data imports

edition_id

string · required

Edition identifier where data will be imported

data_file_base64

string · writeOnly · required

Base64 encoded file content (CSV or Excel)

data_file_name

string · writeOnly · required

Original filename (e.g., 'customers.csv')

name

string · maxLength: 200

Name of the import (optional, auto-generated from filename if not provided)

default_country_code

string | null

Default country code for phone normalization (e.g., '+45' for Denmark)

Create data import › Responses

Serializer for reading data imports with full statistics and metadata

id

string · readOnly · required

Unique identifier for the import

object · readOnly · required

Light readonly serializer for embedding in other resources.

stage

string · enum · readOnly · required

Current import stage. uploaded: File uploaded, column extraction in progress. needs_column_mapping: Columns detected, awaiting column mapping configuration. needs_product_mapping: File parsed with mappings, product assignments needed. importing: Import actively running in background. completed: Import finished successfully. failed: Import encountered an error. cancelled: Import was cancelled by user.

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

uploaded

needs_column_mapping

needs_product_mapping

importing

completed

failed

cancelled

data_file_url

string · readOnly · required

URL to download the uploaded file

data_file_name

string · readOnly · required

Original filename of the uploaded file

readOnly · required

Import statistics including customer, product, and order counts (available in needs_product_mapping, importing, or completed stages)

product_mappings_complete

string · readOnly · required

Whether all product mappings have been assigned to products (available in needs_product_mapping, importing, or completed stages)

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

name

string · maxLength: 200

Name of the import (auto-generated from filename if not provided)

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., +45 for Denmark). If not set, uses edition's default country code.

POST/v1/data-imports

curl --request POST \
  --url https://api.preo.dev/v1/data-imports \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "edition_id": "edition_id",
  "data_file_base64": "data_file_base64",
  "data_file_name": "data_file_name",
  "default_country_code": "default_country_code"
}
'

shell

Example Request Body

{
  "name": "name",
  "edition_id": "edition_id",
  "data_file_base64": "data_file_base64",
  "data_file_name": "data_file_name",
  "default_country_code": "default_country_code"
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "organization": {
    "id": "id",
    "name": "name",
    "slug": "slug",
    "avatar": {
      "thumbnail": "https://www.example.com/path/to/resource",
      "optimized": "https://www.example.com/path/to/resource",
      "large": "https://www.example.com/path/to/resource",
      "original": "https://www.example.com/path/to/resource"
    }
  },
  "edition": {
    "id": "id",
    "full_name": "full_name",
    "slug": "slug",
    "start_date": "2024-08-25T15:00:00Z",
    "end_date": "2024-08-25T15:00:00Z",
    "timezone": "timezone",
    "is_draft": true,
    "published_at": "2024-08-25T15:00:00Z"
  },
  "stage": "uploaded",
  "service": "shopify",
  "default_country_code": "default_country_code",
  "data_file_url": "data_file_url",
  "data_file_name": "data_file_name",
  "parsed_data": {
    "customers_total": 0,
    "customers_existing": 0,
    "products_total": 0,
    "products_existing": 0,
    "orders_total": 0,
    "orders_existing": 0
  },
  "product_mappings_complete": "product_mappings_complete",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z"
}

json

application/json

Get data import details

GET

https://api.preo.dev

/v1/data-imports/{id}

ViewSet for data import operations

Get data import details › path Parameters

id

string · required

A unique value identifying this Data Import.

Get data import details › Responses

200

Serializer for reading data imports with full statistics and metadata

id

string · readOnly · required

Unique identifier for the import

object · readOnly · required

Light readonly serializer for embedding in other resources.

stage

string · enum · readOnly · required

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

uploaded

needs_column_mapping

needs_product_mapping

importing

completed

failed

cancelled

data_file_url

string · readOnly · required

URL to download the uploaded file

data_file_name

string · readOnly · required

Original filename of the uploaded file

readOnly · required

Import statistics including customer, product, and order counts (available in needs_product_mapping, importing, or completed stages)

product_mappings_complete

string · readOnly · required

Whether all product mappings have been assigned to products (available in needs_product_mapping, importing, or completed stages)

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

name

string · maxLength: 200

Name of the import (auto-generated from filename if not provided)

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., +45 for Denmark). If not set, uses edition's default country code.

GET/v1/data-imports/{id}

curl --request GET \
  --url https://api.preo.dev/v1/data-imports/:id

shell

Example Responses

{
  "id": "id",
  "name": "name",
  "organization": {
    "id": "id",
    "name": "name",
    "slug": "slug",
    "avatar": {
      "thumbnail": "https://www.example.com/path/to/resource",
      "optimized": "https://www.example.com/path/to/resource",
      "large": "https://www.example.com/path/to/resource",
      "original": "https://www.example.com/path/to/resource"
    }
  },
  "edition": {
    "id": "id",
    "full_name": "full_name",
    "slug": "slug",
    "start_date": "2024-08-25T15:00:00Z",
    "end_date": "2024-08-25T15:00:00Z",
    "timezone": "timezone",
    "is_draft": true,
    "published_at": "2024-08-25T15:00:00Z"
  },
  "stage": "uploaded",
  "service": "shopify",
  "default_country_code": "default_country_code",
  "data_file_url": "data_file_url",
  "data_file_name": "data_file_name",
  "parsed_data": {
    "customers_total": 0,
    "customers_existing": 0,
    "products_total": 0,
    "products_existing": 0,
    "orders_total": 0,
    "orders_existing": 0
  },
  "product_mappings_complete": "product_mappings_complete",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z"
}

json

application/json

Update data import

PATCH

https://api.preo.dev

/v1/data-imports/{id}

Update data import (PATCH only)

Update data import › path Parameters

id

string · required

A unique value identifying this Data Import.

Update data import › Request Body

Serializer for updating data import settings

name

string · maxLength: 200

Name of the import for easier identification

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., '+45' for Denmark)

Update data import › Responses

200

Serializer for updating data import settings

name

string · maxLength: 200

Name of the import for easier identification

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., '+45' for Denmark)

Cancel data import

POST

https://api.preo.dev

/v1/data-imports/{id}/cancel

Cancel import and transition to cancelled stage. Cannot cancel completed or failed imports.

Cancel data import › path Parameters

id

string · required

A unique value identifying this Data Import.

Cancel data import › Responses

Serializer for reading data imports with full statistics and metadata

id

string · readOnly · required

Unique identifier for the import

object · readOnly · required

Light readonly serializer for embedding in other resources.

stage

string · enum · readOnly · required

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

uploaded

needs_column_mapping

needs_product_mapping

importing

completed

failed

cancelled

data_file_url

string · readOnly · required

URL to download the uploaded file

data_file_name

string · readOnly · required

Original filename of the uploaded file

readOnly · required

Import statistics including customer, product, and order counts (available in needs_product_mapping, importing, or completed stages)

product_mappings_complete

string · readOnly · required

Whether all product mappings have been assigned to products (available in needs_product_mapping, importing, or completed stages)

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

name

string · maxLength: 200

Name of the import (auto-generated from filename if not provided)

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., +45 for Denmark). If not set, uses edition's default country code.

POST/v1/data-imports/{id}/cancel

curl --request POST \
  --url https://api.preo.dev/v1/data-imports/:id/cancel

shell

Example Responses

{
  "id": "id",
  "name": "name",
  "organization": {
    "id": "id",
    "name": "name",
    "slug": "slug",
    "avatar": {
      "thumbnail": "https://www.example.com/path/to/resource",
      "optimized": "https://www.example.com/path/to/resource",
      "large": "https://www.example.com/path/to/resource",
      "original": "https://www.example.com/path/to/resource"
    }
  },
  "edition": {
    "id": "id",
    "full_name": "full_name",
    "slug": "slug",
    "start_date": "2024-08-25T15:00:00Z",
    "end_date": "2024-08-25T15:00:00Z",
    "timezone": "timezone",
    "is_draft": true,
    "published_at": "2024-08-25T15:00:00Z"
  },
  "stage": "uploaded",
  "service": "shopify",
  "default_country_code": "default_country_code",
  "data_file_url": "data_file_url",
  "data_file_name": "data_file_name",
  "parsed_data": {
    "customers_total": 0,
    "customers_existing": 0,
    "products_total": 0,
    "products_existing": 0,
    "orders_total": 0,
    "orders_existing": 0
  },
  "product_mappings_complete": "product_mappings_complete",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z"
}

json

application/json

List column mappings

GET

https://api.preo.dev

/v1/data-imports/{id}/column-mappings

Get list of column mappings for this data import

List column mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

List column mappings › query Parameters

created_after

string · date-time

created_before

string · date-time

edition_id

string | null

Optional: Filter by specific edition. If not provided, shows imports from all accessible editions.

include_cancelled

boolean

Include cancelled imports (default: false)

ordering

string[] · style: form

Ordering

created - Created
-created - Created (descending)
modified - Modified
-modified - Modified (descending)
stage - Stage
-stage - Stage (descending)

Enum values:

-created

-modified

-stage

created

modified

stage

page

integer

A page number within the paginated result set.

page_size

integer

Number of results to return per page (default: 100).

service

string

stage

string · enum

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

cancelled

completed

failed

importing

needs_column_mapping

needs_product_mapping

uploaded

List column mappings › Responses

200

count

integer · required

object[] · required

next

string · uri

previous

string · uri

Update column mappings

PATCH

https://api.preo.dev

/v1/data-imports/{id}/column-mappings/update

Bulk update column mappings. Must be in needs_column_mapping or needs_product_mapping stage. If updating in needs_product_mapping stage, parsed data and product mappings will be cleared and stage will revert to needs_column_mapping.

Update column mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

Update column mappings › query Parameters

created_after

string · date-time

created_before

string · date-time

edition_id

string | null

Optional: Filter by specific edition. If not provided, shows imports from all accessible editions.

include_cancelled

boolean

Include cancelled imports (default: false)

ordering

string[] · style: form

Ordering

created - Created
-created - Created (descending)
modified - Modified
-modified - Modified (descending)
stage - Stage
-stage - Stage (descending)

Enum values:

-created

-modified

-stage

created

modified

stage

page

integer

A page number within the paginated result set.

page_size

integer

Number of results to return per page (default: 100).

service

string

stage

string · enum

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

cancelled

completed

failed

importing

needs_column_mapping

needs_product_mapping

uploaded

Update column mappings › Request Body

Serializer for updating column mappings

object[]

List of column mappings to update

Update column mappings › Responses

count

integer · required

object[] · required

next

string · uri

previous

string · uri

PATCH/v1/data-imports/{id}/column-mappings/update

curl --request PATCH \
  --url https://api.preo.dev/v1/data-imports/:id/column-mappings/update \
  --header 'Content-Type: application/json' \
  --data '
{
  "mappings": [
    {
      "id": "id",
      "column_type": "customer_email",
      "metadata_key": "metadata_key"
    }
  ]
}
'

shell

Example Request Body

{
  "mappings": [
    {
      "id": "id",
      "column_type": "customer_email",
      "metadata_key": "metadata_key"
    }
  ]
}

json

Example Responses

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "id",
      "column": "column",
      "column_type": "column_type",
      "metadata_key": "metadata_key",
      "order": "order"
    }
  ]
}

json

application/json

Preview import orders

GET

https://api.preo.dev

/v1/data-imports/{id}/preview

Get paginated preview of orders. Available in needs_product_mapping, importing, or completed stages. Max 1000 per request.

Preview import orders › path Parameters

id

string · required

A unique value identifying this Data Import.

Preview import orders › query Parameters

limit

integer

Number of orders to return (max 1000)

Default: 50

offset

integer

Starting position in the result set

Default: 0

Preview import orders › Responses

Response serializer for preview action with pagination

total

integer · required

Total number of orders in the import

limit

integer · required

Number of orders in this response

offset

integer · required

Starting position in the full result set

object[] · required

List of orders

order_metadata_keys

string[]

List of all order metadata keys found across all orders

purchase_metadata_keys

string[]

List of all purchase metadata keys found across all products

GET/v1/data-imports/{id}/preview

curl --request GET \
  --url https://api.preo.dev/v1/data-imports/:id/preview

shell

Example Responses

{
  "total": 0,
  "limit": 0,
  "offset": 0,
  "orders": [
    {
      "email": "test@example.com",
      "phone_number": "phone_number",
      "phone_number_original": "phone_number_original",
      "phone_number_valid": true,
      "first_name": "first_name",
      "last_name": "last_name",
      "order_id": "order_id",
      "products": [
        {
          "product_name": "product_name",
          "product_sku": "product_sku",
          "quantity": 0,
          "item_id": "item_id",
          "unit_price": 0,
          "purchase_metadata": {
            "key": {}
          }
        }
      ],
      "order_metadata": {
        "key": {}
      }
    }
  ],
  "order_metadata_keys": [
    "string"
  ],
  "purchase_metadata_keys": [
    "string"
  ]
}

json

application/json

Process column mappings

POST

https://api.preo.dev

/v1/data-imports/{id}/process-mappings

Parse file using column mappings and create product mappings. Transitions to needs_product_mapping stage. Must be in needs_column_mapping stage.

Process column mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

Process column mappings › Responses

Serializer for reading data imports with full statistics and metadata

id

string · readOnly · required

Unique identifier for the import

object · readOnly · required

Light readonly serializer for embedding in other resources.

stage

string · enum · readOnly · required

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

uploaded

needs_column_mapping

needs_product_mapping

importing

completed

failed

cancelled

data_file_url

string · readOnly · required

URL to download the uploaded file

data_file_name

string · readOnly · required

Original filename of the uploaded file

readOnly · required

Import statistics including customer, product, and order counts (available in needs_product_mapping, importing, or completed stages)

product_mappings_complete

string · readOnly · required

Whether all product mappings have been assigned to products (available in needs_product_mapping, importing, or completed stages)

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

name

string · maxLength: 200

Name of the import (auto-generated from filename if not provided)

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., +45 for Denmark). If not set, uses edition's default country code.

POST/v1/data-imports/{id}/process-mappings

curl --request POST \
  --url https://api.preo.dev/v1/data-imports/:id/process-mappings

shell

Example Responses

{
  "id": "id",
  "name": "name",
  "organization": {
    "id": "id",
    "name": "name",
    "slug": "slug",
    "avatar": {
      "thumbnail": "https://www.example.com/path/to/resource",
      "optimized": "https://www.example.com/path/to/resource",
      "large": "https://www.example.com/path/to/resource",
      "original": "https://www.example.com/path/to/resource"
    }
  },
  "edition": {
    "id": "id",
    "full_name": "full_name",
    "slug": "slug",
    "start_date": "2024-08-25T15:00:00Z",
    "end_date": "2024-08-25T15:00:00Z",
    "timezone": "timezone",
    "is_draft": true,
    "published_at": "2024-08-25T15:00:00Z"
  },
  "stage": "uploaded",
  "service": "shopify",
  "default_country_code": "default_country_code",
  "data_file_url": "data_file_url",
  "data_file_name": "data_file_name",
  "parsed_data": {
    "customers_total": 0,
    "customers_existing": 0,
    "products_total": 0,
    "products_existing": 0,
    "orders_total": 0,
    "orders_existing": 0
  },
  "product_mappings_complete": "product_mappings_complete",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z"
}

json

application/json

List product mappings

GET

https://api.preo.dev

/v1/data-imports/{id}/product-mappings

Get list of product mappings for this data import

List product mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

List product mappings › query Parameters

created_after

string · date-time

created_before

string · date-time

edition_id

string | null

Optional: Filter by specific edition. If not provided, shows imports from all accessible editions.

include_cancelled

boolean

Include cancelled imports (default: false)

ordering

string[] · style: form

Ordering

created - Created
-created - Created (descending)
modified - Modified
-modified - Modified (descending)
stage - Stage
-stage - Stage (descending)

Enum values:

-created

-modified

-stage

created

modified

stage

page

integer

A page number within the paginated result set.

page_size

integer

Number of results to return per page (default: 100).

service

string

stage

string · enum

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

cancelled

completed

failed

importing

needs_column_mapping

needs_product_mapping

uploaded

List product mappings › Responses

200

count

integer · required

object[] · required

next

string · uri

previous

string · uri

GET/v1/data-imports/{id}/product-mappings

curl --request GET \
  --url https://api.preo.dev/v1/data-imports/:id/product-mappings

shell

Example Responses

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "id",
      "product_sku": "product_sku",
      "product_name": "product_name",
      "product": {
        "api_id": "api_id",
        "name": "name",
        "is_draft": true,
        "images": [
          {
            "thumbnail": "https://www.example.com/path/to/resource",
            "optimized": "https://www.example.com/path/to/resource",
            "large": "https://www.example.com/path/to/resource",
            "original": "https://www.example.com/path/to/resource"
          }
        ]
      },
      "variant": {
        "api_id": "api_id",
        "name": "name"
      },
      "quantity_in_import": "quantity_in_import"
    }
  ]
}

json

application/json

Update product mappings

PATCH

https://api.preo.dev

/v1/data-imports/{id}/product-mappings/update

Bulk update product mappings. Must be in needs_product_mapping or importing stage.

Update product mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

Update product mappings › query Parameters

created_after

string · date-time

created_before

string · date-time

edition_id

string | null

Optional: Filter by specific edition. If not provided, shows imports from all accessible editions.

include_cancelled

boolean

Include cancelled imports (default: false)

ordering

string[] · style: form

Ordering

created - Created
-created - Created (descending)
modified - Modified
-modified - Modified (descending)
stage - Stage
-stage - Stage (descending)

Enum values:

-created

-modified

-stage

created

modified

stage

page

integer

A page number within the paginated result set.

page_size

integer

Number of results to return per page (default: 100).

service

string

stage

string · enum

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

cancelled

completed

failed

importing

needs_column_mapping

needs_product_mapping

uploaded

Update product mappings › Request Body

Serializer for updating product mappings

object[]

List of product mappings to update

Update product mappings › Responses

count

integer · required

object[] · required

next

string · uri

previous

string · uri

PATCH/v1/data-imports/{id}/product-mappings/update

curl --request PATCH \
  --url https://api.preo.dev/v1/data-imports/:id/product-mappings/update \
  --header 'Content-Type: application/json' \
  --data '
{
  "mappings": [
    {
      "id": "id",
      "product_id": "product_id",
      "variant_id": "variant_id"
    }
  ]
}
'

shell

Example Request Body

{
  "mappings": [
    {
      "id": "id",
      "product_id": "product_id",
      "variant_id": "variant_id"
    }
  ]
}

json

Example Responses

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "id",
      "product_sku": "product_sku",
      "product_name": "product_name",
      "product": {
        "api_id": "api_id",
        "name": "name",
        "is_draft": true,
        "images": [
          {
            "thumbnail": "https://www.example.com/path/to/resource",
            "optimized": "https://www.example.com/path/to/resource",
            "large": "https://www.example.com/path/to/resource",
            "original": "https://www.example.com/path/to/resource"
          }
        ]
      },
      "variant": {
        "api_id": "api_id",
        "name": "name"
      },
      "quantity_in_import": "quantity_in_import"
    }
  ]
}

json

application/json

Start import process

POST

https://api.preo.dev

/v1/data-imports/{id}/start-import

Begin data import. Validates product mappings are complete. Transitions to importing stage. Must be in needs_product_mapping stage. Set ignore_warnings to proceed even when some products are unmapped (they will be skipped).

Start import process › path Parameters

id

string · required

A unique value identifying this Data Import.

Start import process › query Parameters

ignore_warnings

boolean

Proceed with import even when some products are unmapped (they will be skipped)

Default: false

Start import process › Responses

Serializer for reading data imports with full statistics and metadata

id

string · readOnly · required

Unique identifier for the import

object · readOnly · required

Light readonly serializer for embedding in other resources.

stage

string · enum · readOnly · required

uploaded - Uploaded
needs_column_mapping - Needs Column Mapping
needs_product_mapping - Needs Product Mapping
importing - Importing
completed - Completed
failed - Failed
cancelled - Cancelled

Enum values:

uploaded

needs_column_mapping

needs_product_mapping

importing

completed

failed

cancelled

data_file_url

string · readOnly · required

URL to download the uploaded file

data_file_name

string · readOnly · required

Original filename of the uploaded file

readOnly · required

Import statistics including customer, product, and order counts (available in needs_product_mapping, importing, or completed stages)

product_mappings_complete

string · readOnly · required

Whether all product mappings have been assigned to products (available in needs_product_mapping, importing, or completed stages)

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

name

string · maxLength: 200

Name of the import (auto-generated from filename if not provided)

default_country_code

string | null · maxLength: 6

Default country code for phone number normalization (e.g., +45 for Denmark). If not set, uses edition's default country code.

POST/v1/data-imports/{id}/start-import

curl --request POST \
  --url https://api.preo.dev/v1/data-imports/:id/start-import

shell

Example Responses

{
  "id": "id",
  "name": "name",
  "organization": {
    "id": "id",
    "name": "name",
    "slug": "slug",
    "avatar": {
      "thumbnail": "https://www.example.com/path/to/resource",
      "optimized": "https://www.example.com/path/to/resource",
      "large": "https://www.example.com/path/to/resource",
      "original": "https://www.example.com/path/to/resource"
    }
  },
  "edition": {
    "id": "id",
    "full_name": "full_name",
    "slug": "slug",
    "start_date": "2024-08-25T15:00:00Z",
    "end_date": "2024-08-25T15:00:00Z",
    "timezone": "timezone",
    "is_draft": true,
    "published_at": "2024-08-25T15:00:00Z"
  },
  "stage": "uploaded",
  "service": "shopify",
  "default_country_code": "default_country_code",
  "data_file_url": "data_file_url",
  "data_file_name": "data_file_name",
  "parsed_data": {
    "customers_total": 0,
    "customers_existing": 0,
    "products_total": 0,
    "products_existing": 0,
    "orders_total": 0,
    "orders_existing": 0
  },
  "product_mappings_complete": "product_mappings_complete",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z"
}

json

application/json

Validate column mappings

POST

https://api.preo.dev

/v1/data-imports/{id}/validate-mappings

Pre-flight validation without processing file. Must be in needs_column_mapping stage.

Validate column mappings › path Parameters

id

string · required

A unique value identifying this Data Import.

Validate column mappings › Responses

Response serializer for validate-mappings action

valid

boolean · required

object

Import external orders

POST

https://api.preo.dev

/v1/data-imports/external-orders

Import orders from an external system. Orders are queued for asynchronous processing. An ORDER_COMPLETED webhook event will be sent when each order's processing completes. Orders are deduplicated by order_id - duplicates are silently skipped and reported in response. Requires manager or admin role on the target edition.

Import external orders › Request Body

Request serializer for importing external orders.

edition_id

string · maxLength: 255 · required

Edition API ID (edt_xxx)

object[] · required

List of orders to import

Import external orders › Responses

Response serializer for order import.

status

string · enum · required

Import status

queued - queued

Enum values:

queued

queued_count

integer · required

Number of orders queued for processing

skipped_count

integer · required

Number of orders skipped (duplicates)

skipped_order_ids

string[] · required

List of order_ids that were skipped as duplicates

POST/v1/data-imports/external-orders

curl --request POST \
  --url https://api.preo.dev/v1/data-imports/external-orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "edition_id": "edition_id",
  "orders": [
    {
      "email": "test@example.com",
      "phone_number": "phone_number",
      "first_name": "first_name",
      "last_name": "last_name",
      "order_id": "order_id",
      "items": [
        {
          "product_id": "product_id",
          "variant_id": "variant_id",
          "option_ids": [
            "string"
          ],
          "quantity": 1,
          "price": 0,
          "purchase_metadata": {}
        }
      ],
      "order_metadata": {}
    }
  ]
}
'

shell

Example Request Body

{
  "edition_id": "edition_id",
  "orders": [
    {
      "email": "test@example.com",
      "phone_number": "phone_number",
      "first_name": "first_name",
      "last_name": "last_name",
      "order_id": "order_id",
      "items": [
        {
          "product_id": "product_id",
          "variant_id": "variant_id",
          "option_ids": [
            "string"
          ],
          "quantity": 1,
          "price": 0,
          "purchase_metadata": {}
        }
      ],
      "order_metadata": {}
    }
  ]
}

json

Example Responses

{
  "status": "queued",
  "queued_count": 0,
  "skipped_count": 0,
  "skipped_order_ids": [
    "string"
  ]
}

json

application/json

Files Campaigns