Broadtype and Subtype Imports

Use Retrend imports to register your browsing taxonomy before loading products. This guide covers preparing JSON Lines files for broadtype and subtype 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

1. Prepare a newline-delimited JSONL file whose objects match one of the schemas below.
2. POST /v2/imports/upload with multipart/form-data that includes the file plus the matching import_type (broadtype or subtype).
3. Store the job_id returned in the upload response.
4. Periodically POST /v2/imports/check with the job_id until is_complete: true.
5. 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 broadtype or subtype. 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=broadtype \
  -F file=@broadtypes.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 record. Use UTF-8 encoding, avoid trailing commas, and ensure optional fields are either omitted or set to null.

Broadtype schema

Broad types define the top-level taxonomy categories shown to shoppers.

Example broadtype lines:

{"name":"Wine","description":"Still and sparkling wines spanning red, white, and rosé.","image_url":"https://cdn.example.com/images/wine.jpg"}
{"name":"Spirits","description":"Core liquor categories for cocktails and sipping.","image_url":"https://cdn.example.com/images/spirits.jpg"}

Subtype schema

Subtypes nest under a broader category. Import matching broad types first.

Example subtype lines:

{"name":"Red","description":"Full-bodied to light-bodied red wines.","broadtype_name":"Wine"}
{"name":"Bitters","description":"Cocktail bitters and flavoring agents.","broadtype_name":"Spirits"}

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 taxonomy imports

• Import broadtype before subtype to satisfy the broadtype_name relationship.
• Keep names stable; products reference a subtype name plus its broad type name.
• Start with small sample files to validate formatting before sending large payloads.