Merchandising Pipeline — User Guide

Who this guide is for

Anyone who uses the Merchandising pipeline through the website. You do not need to know any programming language. This guide walks through every page, button, and upload field you will encounter, in plain language.

What this guide covers

What each button does, what files you can upload, what the different statuses mean, where to find your task IDs, and how to handle the most common situations (downloading results, resuming a failed task, cancelling, finding an old task).

What this guide does NOT cover

• The contents of the configuration file. For everything about how to write or edit the YAML configuration file, see configuration-guide.
• The category-to-attribute mapping CSV file. For how to set that file up, see cat-to-att.md.

Table of Contents#

1. The two pages, at a glance
2. The Merchandising page (your task list)
3. Creating a new task — the Create Merchandising Task page
4. Task IDs: what they are and where to find them
5. Task statuses explained
6. Common workflows
7. Troubleshooting

1. The two pages, at a glance#

The Merchandising pipeline has two pages:

You will spend most of your time on the Create Merchandising Task page. You only visit the Merchandising page when you want to check your previous runs.

You can move between them with the Create Task button on the task list page (which takes you to the create form) and the Back to Merchandising button at the top of the create form (which brings you back).

2. The Merchandising Task Page#

The task list page is what you see when you go to Merchandising in the site navigation. It shows every merchandising task you have submitted, newest first.

The header#

At the top of the page you will see the page title Merchandising with a short description underneath. To the right of the title there are two buttons:

The four summary cards#

Just below the header you will see four small information cards in a row:

The tasks table#

Below the summary cards is the main task list. Each row is one merchandising task, and each row has six columns.

The action buttons (per row)#

The buttons you see on each row depend on the task's status. Not every button is shown for every task.

While any of these buttons is doing its work, it shows a small spinning icon and is disabled so you can't click it twice.

Pagination#

At the bottom of the table you will see how many tasks are on the current page out of the total, plus Previous and Next buttons and the current page number. Each page shows up to 10 tasks. Use the buttons to move through your history.

Automatic refresh#

If any task on the current page is still active (queued, pending, or processing), the table refreshes itself every five seconds in the background, so you can leave the page open and watch progress live. The refresh is silent — the loading spinner does not appear during the automatic refreshes, only when you click the Refresh button yourself.

When all tasks on the current page have settled (completed, failed, cancelled, or paused), the automatic refresh stops on its own.

3. Creating a new task — the Create Merchandising Task page#

You reach this page by clicking Create Task on the main Merchandising page (or by going directly to /merchandising/pipeline). This is the form where you upload your files and start a new run.

At the very top of the page is a Back to Merchandising button that takes you back to your task list without submitting anything.

The form is broken into several cards, working from top to bottom. You don't have to fill in everything — only the CSV file, the configuration file, and the column mapping are required.

Card 1: CSV Data File#

This is where you upload your input spreadsheet (the list of products you want the pipeline to process).

• What to upload: A .csv file. Other file types are rejected with an error.
• How to upload: Either drag the file from your computer onto the dashed box, or click Browse Files and pick the file from a dialog.
• After upload: The filename appears with a small clear (✕) button you can click if you want to swap it out for a different file.

The CSV needs to have a header row and at least one data row. You'll map these fields later.

Card 2: Configuration File#

This is where you upload the YAML configuration file that controls every detail of how the pipeline processes your products — what to research, what content to generate, how to validate it, what marketplaces to publish to, and so on.

• What to upload: A .yaml or .yml file. Other file types are rejected with an error.
• How to upload: Click Browse Files and pick the file.
• After upload: The filename appears with a clear (✕) button. You can also click View Configuration to expand a preview of the parsed contents.

For how to write or edit configuration files, see configuration-guide. That guide is the complete reference for every setting you can put in the YAML file.

The Help button#

To the right of the Configuration File heading there is a small Help button (a question-mark icon). Clicking it opens an in-page assistant that can answer questions about your configuration file. Use it if you are unsure how to write a configuration file from scratch, or if you want to ask questions about one you already have.

Card 3: Category-to-Attribute Mapping (Optional)#

This card lets you upload a CSV file that maps product categories to the attributes you want generated for each one. It is optional — you only upload it if your configuration uses category-driven attribute generation.

• What to upload: A .csv file.
• How to upload: Click Browse Files and pick the file.
• After upload: The filename appears with a clear (✕) button.
• Requirement reminder: For this file to actually be used, your configuration file must include categorization and at least one of generate_attributes or extract_attributes in its generation steps. If those are missing, the upload is accepted but ignored.

For the format of this file — what columns it needs, what the values look like, and how the pipeline matches categories to attributes — see cat-to-att.md.

Card 4: 3PL Replacement Files (Optional)#

This card lets you upload up to three CSV files of marketplace-specific find-and-replace terms — one for Amazon, one for eBay, and one for Walmart. They are completely optional.

• How to open it: Click the 3PL Replacement Files (Optional) heading. The card collapses and expands when clicked, so it stays out of the way until you need it.
• What to upload: A .csv file in each of the three slots (Amazon, eBay, Walmart). You can upload one, two, or all three. None are required.
• How to upload each one: Click Browse Files under the marketplace label and pick the file.
• After upload: The filename appears with a clear (✕) button next to it.

These files override any inline replacement terms in your configuration file for the matching marketplace.

Card 5: Additional Data Sources#

This card lets you attach extra reference material to the task — text files or JSON files containing information that should be available during processing.

• What to upload: One or more .txt or .json files. You can upload multiple files at once.
• How to upload: Click Browse Files and pick the files.
• After upload: Each uploaded file appears in a list, with its name, a TEXT or JSON label, and a View content expandable preview. Each file has its own small clear (✕) button if you want to remove just that one.

If you are want to use a pdf catalog as a part of the Generation Steps, first process it through the "Catalog Processor" page, then upload the output here.

Card 6: Map Columns (appears after you upload the CSV)#

After you upload your input CSV, a new card appears called Map Columns. This is where you tell the pipeline which of your spreadsheet columns hold the three required fields:

Each field has a dropdown that lists every column header from your CSV. Pick the matching column for each one.

When you have selected all three, click Confirm Mapping. If you change your mind, click Cancel to clear the CSV and start over with a new file.

Card 7: Additional Fields (Optional, appears after column mapping is confirmed)#

After you confirm the three required mappings, a new card appears letting you choose extra columns from your CSV that should also be used as context during content generation. This is useful when your CSV has helpful columns the pipeline would otherwise ignore (for example, a brand column, a manufacturer column, or a category column).

• How to add a column: Pick it from the Add a column dropdown. The dropdown lists every CSV column except the three you already mapped and any extra columns you have already added.
• How to remove a column: Each added column appears as a small badge with an X. Click the X to remove it.

You can add as many extra columns as you want, or none at all.

Card 8: Mapped Data Preview (appears after column mapping is confirmed)#

This card shows a small preview of how your CSV will look after the column mapping is applied — the first five rows, with three columns: Title, Description, and Main Product Identifier. Use it to sanity-check that you mapped the right columns.

If something looks wrong, click Upload New File to start over with a different CSV (or to remap the columns of the same one).

The Create Task button#

Once you have:

1. Uploaded a CSV file, and
2. Uploaded a configuration file, and
3. Confirmed the column mapping,

a large Create Task button appears at the bottom of the form. Clicking it submits everything — your CSV, your configuration, your column mapping, your extra columns, and any optional files (category-to-attribute mapping, 3PL replacement files, additional data sources) — as a new merchandising task.

The button is disabled (greyed out) until all three required things are in place. While the task is being submitted, the button is disabled and the form switches into a "task created" view.

Card 9: Task Progress (appears after a task is created)#

As soon as your task is created, a new Task Progress card appears at the bottom of the page.

This card shows:

• The Task ID (in small monospaced text right under the heading) — write it down or copy it if you ever want to find this exact task again later. (See section 4.)
• A live progress bar that fills up as the task processes rows.
• A status message that updates as the task progresses, telling you what it is doing right now (queued, processing row X of Y, completed, failed, or cancelled).
• One or more action buttons that depend on the task's status:

The progress bar updates roughly every three seconds as long as the task is running. You can leave the page open and watch live, or you can navigate away — the task keeps running on the server either way, and you can come back to it later from the main Merchandising page.

4. Task IDs: what they are and where to find them#

Every merchandising task you submit gets a unique task ID the moment it is created. The task ID is what the system uses to refer to your specific run, and it is what you use to find a particular task again later.

What a task ID looks like#

A task ID is a long, unique string of letters, numbers, and hyphens. It is shown in small grey monospaced text everywhere it appears, so it's easy to spot.

Where you will see the task ID#

The task ID appears in two places in the user interface:

1. On the Create Merchandising Task page, immediately after you submit a task.

As soon as you click Create Task and the task is accepted, a new Task Progress card appears at the bottom of the page. The task ID is shown in monospaced text right below the "Task Progress" heading, like this:

Task Progress

Task ID: {long-task-id-string}

This is the moment to copy or write down the task ID if you might want to come back to this exact task later (for example, if your browser crashes or you close the tab). The task is also automatically added to your task list, so you can usually find it again there.

2. On the main Merchandising page, in the Files column of the task table.

Every row of the task list shows the task ID in small grey monospaced text directly underneath the input CSV filename. Each row's task ID is unique to that row.

Why task IDs matter#

You generally don't need to type the task ID anywhere yourself — the buttons in the task list (Pause, Resume, Cancel, Download) already know which task they are acting on. But the task ID is useful when:

• You want to reference a specific task in a support request or chat with your team. ("My task ID abc-123-def-456 failed — can you take a look?")
• You want to verify that a task you just submitted is the one you are looking at in the list, especially if you submitted several tasks with similar filenames in quick succession.
• You uploaded a file with a very generic name (like products.csv) and need a way to tell two tasks apart in the list.

Where the result file lives#

When you download the results of a completed task, the downloaded file is automatically named after your input CSV (for example, january_products_result.csv for an input file called january_products.csv). If your input CSV had no name for any reason, the downloaded file falls back to using the task ID instead, like {task-id}_result.csv.

5. Task statuses explained#

Each task has one of seven possible statuses at any given time. The status appears as a coloured badge in the Status column of the task list and in the status message of the Task Progress card on the create page.

About errored rows inside a successful task#

A task can be completed and still have errored rows. The pipeline does its best to process every row independently, so even if some rows fail, the rest still finish and the task as a whole is marked complete. Look at the green Success pill and the red Errors pill under the progress bar to see how many rows fell into each bucket. The result CSV will contain all the rows the pipeline could process; rows that errored will appear with whatever partial information was produced before the failure.

6. Common workflows#

This section walks through the most common things you will want to do, end to end.

Submitting a new task#

1. From the Merchandising page, click Create Task.
2. In the CSV Data File card, drag your CSV onto the upload box, or click Browse Files and pick it.
3. In the Configuration File card, click Browse Files and pick your YAML configuration. (If you do not have one, click the Help button next to the heading to get help building one.)
4. (Optional) In the Category-to-Attribute Mapping card, upload your category mapping CSV.
5. (Optional) Open the 3PL Replacement Files card and upload any per-marketplace replacement CSVs you need.
6. (Optional) In the Additional Data Sources card, upload any reference text or JSON files.
7. In the Map Columns card that appeared after the CSV upload, pick the right columns from your CSV for Title, Description, and Main Product Identifier, then click Confirm Mapping.
8. (Optional) In the Additional Fields card, add any extra CSV columns that should be used as context.
9. Look at the Mapped Data Preview card to make sure the first five rows look correct.
10. Click the big Create Task button at the bottom of the form.
11. The Task Progress card appears with your Task ID. Copy it down if you want.
12. Either watch the progress live, or click Back to Merchandising to return to the task list.

Downloading the results of a completed task#

You have two ways to do this.

From the task list (recommended):

1. Go to the Merchandising page.
2. Find your task in the table. Look for the green completed badge.
3. Click the Download button on that row.
4. The result CSV is saved to your computer with the filename pattern {your-input-name}_result.csv.

From the Task Progress card right after submitting:

1. After your task is created, stay on the Create Merchandising Task page.
2. Watch the progress bar fill up.
3. When the status changes to completed, click Download Results.
4. The result CSV is saved to your computer.

Finding an old task#

1. Go to the Merchandising page.
2. Use the Previous and Next buttons at the bottom of the table to page through your task history. Each page shows 10 tasks, with newer tasks first.
3. Look at the Files column to find your task by its CSV filename, or by the small task ID shown underneath.

Resuming a failed task#

1. Go to the Merchandising page.
2. Find the task that has the red failed badge.
3. Read the error message shown under the badge to understand what went wrong.
4. If the error looks recoverable, click Resume. The pipeline will start again from the chunk that failed — anything that was already processed successfully is kept.
5. The status will change back to processing and the progress bar will pick up from where it left off.

If the error is not something the pipeline can recover from on its own (for example, a problem with your input file or your configuration), it is usually better to fix the underlying issue and create a new task instead.

Pausing and resuming a long task#

1. While the task is processing (or pending), click Pause on its row.
2. The status will change to paused. No more rows will be processed until you resume.
3. To resume, click Resume on the same row. The status will go back to processing and the pipeline will pick up where it left off.

Pausing is useful when you need to free up capacity for something else, or when you realize a configuration mistake and want to stop the task before it does more work.

Cancelling a task#

1. Find the task you want to stop on the Merchandising page.
2. Click Cancel on its row.
3. The status will change to cancelled.

Important: Cancelled tasks cannot be resumed. If you cancel a task by accident, you will need to submit a new one with the same files.

7. Troubleshooting#

I uploaded a file but the system says it's the wrong type#

The merchandising pipeline is strict about file extensions:

If you uploaded the right kind of file but it has a different extension (for example, a YAML file saved as .txt), rename it to use the correct extension and try again.

The Create Task button is greyed out#

The Create Task button only becomes clickable when all three of the following are true:

1. You have uploaded a CSV file.
2. You have uploaded a configuration file.
3. You have confirmed the column mapping by clicking Confirm Mapping in the Map Columns card.

Look back through the form and make sure all three are done. The button will light up as soon as the last one is in place.

My task failed — what does the error mean?#

When a task fails, the error message is shown directly under the red failed badge in the Status column of the task list (and also in the Task Progress card on the create page if you're still on it). Read the message — it usually tells you what went wrong (a missing field, a configuration problem, a marketplace name that isn't recognized, an attribute mapping issue, etc.).

If the problem looks fixable on the pipeline side, click Resume and the task will try again from where it left off. If the problem is in your input file or configuration, fix it and submit a new task instead.

The progress bar is not moving#

Two things could be happening:

1. Your task is queued, not yet running. The status will say pending or queued. The pipeline is waiting for capacity to start your task. This is normal — it should start within a short time.
2. Your task has stalled or failed. Click Refresh at the top of the task list to force an immediate update. If the status is now failed, read the error message and try to resume.

I can't find a task I just created#

Every newly created task is automatically added to the top of your task list on the Merchandising page. If you don't see it:

1. Make sure you are on page 1 of the task list (newest tasks come first). Use the Previous button to walk back to the first page if you have paged forward.
2. Click Refresh at the top of the page to force an immediate update.
3. Check that you are signed in to the same account you used to create the task. The task list only shows your own tasks.

The task list keeps refreshing on its own — can I stop it?#

The task list refreshes itself every five seconds only when there is at least one active task on the current page (one with a status of pending, queued, or processing). The refresh stops automatically once every task on the page has settled. If the auto-refresh is happening at a moment that's inconvenient, switch to a different page of the list — the auto-refresh only watches the current page.