Store Imports

Docs

Store Imports

Upload JSONL store records with locations and metadata using the imports API.

Use Retrend imports to load your store directory before attaching stock and sales signals. This guide covers preparing a JSON Lines file for store imports and calling the two endpoints you’ll use:

POST <https://api.retrend.ai/v2/imports/upload> uploads a JSONL file for one import type.
POST <https://api.retrend.ai/v2/imports/check> polls the background job created during the upload.

These examples assume you already created a session token as described in API Dependencies and you will authenticate each request with organization-id and x-session headers.

Import workflow

Prepare a newline-delimited JSONL file whose objects match the store schema below.
POST /v2/imports/upload with multipart/form-data that includes the file plus import_type=store.
Store the job_id returned in the upload response.
Periodically POST /v2/imports/check with the job_id until is_complete: true.
Review validation errors in the dashboard (the API responds synchronously only for structural problems).

Upload request format

The upload endpoint accepts multipart/form-data with two fields:

import_type — use store. Each file targets exactly one type.
file — binary attachment of your .jsonl file.

curl -X POST "https://api.retrend.ai/v2/imports/upload" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -F import_type=store \
  -F file=@stores.jsonl

The response includes success (boolean) and job_id (UUID). success reflects whether the upload was accepted; data validation happens asynchronously based on the job_id.

Preparing JSONL payloads

Each JSON object in your file represents one store. Use UTF-8 encoding, avoid trailing commas, and ensure optional fields are either omitted or set to null.

Store schema

Field	Type	Required	Notes
`store_id`	string	Yes	Stable ID from your system.
`name`	string	Yes	Store name.
`num`	integer	No	Internal store number. If omitted, a number is assigned.
`is_virtual`	boolean	Yes	Mark `true` for online/virtual locations.
`is_active`	boolean	Yes	Controls whether the store is available.
`address`	string	No	Street address.
`city`	string	No	City.
`state`	string	No	State or region.
`zip_code`	string	No	Postal code.
`county`	string	No	County if applicable.
`phone`	string	No	Store phone number.
`lat`	number	No	Latitude coordinate.
`long`	number	No	Longitude coordinate.

Example store lines:

{"store_id":"store-001","name":"Downtown Flagship","num":1,"is_virtual":false,"is_active":true,"address":"123 Main St","city":"Austin","state":"TX","zip_code":"78701","phone":"+1-512-555-0101","lat":30.2672,"long":-97.7431}
{"store_id":"store-online","name":"Online Store","is_virtual":true,"is_active":true,"address":null,"city":null,"state":null,"zip_code":null,"lat":null,"long":null}

Checking import status

Once you have a job_id, poll /v2/imports/check until the response indicates completion:

curl -X POST "https://api.retrend.ai/v2/imports/check" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"job_id\": \"12345678-1234-1234-1234-123456789012\"}"

The API responds with:

{
  "is_complete": false
}

Keep polling (with exponential backoff) until is_complete switches to true. After completion, review any row-level issues inside the dashboard's import history to address validation failures.

Tips for smooth store imports

Import stores before stock so store_id references resolve.
Use consistent store_id formats; stock rows require exact matches.
Include coordinates when available to improve location-based recommendations.

Imports API: Recipes Imports API: Types