plan: Pro plan only (R6)
screens: The top tab "Update tracking" (page heading "Update tracking numbers") / step bar "Select file" → "Preview" → "Apply"
verified_from: The tracking number update implementation (decision functions, confirmation screen) and design notes. The human-facing manual describes the old screen
ui_verified: Field names were confirmed from the code. The main routes were confirmed on a development store, but some routes remain unconfirmed
caution: This decision actually marks orders as "fulfilled" (a notification email may go to customers). Do not answer assertively with "it's fine"
note: In the English admin some labels of the CSV screen may be shown in Japanese; both the English label and the Japanese label are given where known.
SUMMARY
When you upload the CSV of tracking numbers issued by the carrier’s system, Shopify orders are marked “fulfilled” and the tracking numbers are registered (if already fulfilled, the tracking number is overwritten). How a Shopify fulfillment (a unit shown in the “Unfulfilled” card) is matched to a CSV row is decided by the settings and the current state of that order. When in doubt, do not execute; stop at the confirmation screen and show the reason.
Terms
| Term | Meaning |
|---|
| Unfulfilled fulfillment unit | One “Unfulfilled” card in the order detail of the Shopify admin (a group of items to ship). |
| Fulfilled fulfillment unit | One “Fulfilled” card in the admin. A tracking number is attached. |
| Overwrite | Replacing the tracking number of a fulfilled unit with the CSV value. |
| Partial shipment | Shipping only the specified items out of an unfulfilled unit. The rest stay unfulfilled. |
| History | The “record of exported rows” saved when a CSV is exported. Used only to know “which row is which product”. |
FACTS
TU-1 The decision is made from Shopify's "current state". It is not decided from the "updated" record in the history.
(An order whose unfulfilled unit was recreated after cancellation can be treated as "unfulfilled only" as it is)
TU-2 When in doubt, stop and show the reason. No guessing or automatic assignment.
Examples of stopping: the product cannot be decided / fulfilled and unfulfilled are mixed / there are several candidates / there is no history / settings that cannot be combined
TU-3 The "Action" shown on the confirmation screen and the process that is executed come from the same decision.
"Rows that will not be applied" appear on the confirmation screen with their reasons (they are not skipped silently).
TU-4 An order that does not match stops only that order; other orders go on.
TU-5 If notification is OFF, no email goes to the customer.
TU-6 To read tracking numbers from the CSV, the column numbers (counted from 1) of the order ID column and the tracking column, and the encoding, must match.
The initial templates contain the default column numbers of each carrier.
TU-7 If the same column is specified for the order ID column and the tracking column, a warning appears and it cannot be executed.
TU-8 An order whose fetch failed is not treated as "0 fulfilled units" and shipped (a fetch failure stops execution with a red banner).
Shipment methods (decided by the template’s split setting)
The method is decided automatically from the template’s split setting. The merchant does not choose it.
| Method | What kind of template | What it does |
|---|
| A Together | A template that does not split orders (“Split fulfillment of shipments” is OFF) | Ships the unfulfilled units of the order together with the same tracking number |
| B Per product | “Split every row”, or a template where specific products are separate waybill rows and “Split fulfillment of shipments” is ON | Partially ships only the product of the CSV row |
| C Per fulfillment unit | A template using “Export split by delivery fulfillment unit (support for split shipping)” | Ships per unfulfilled unit |
Decision table (method × the order’s state on Shopify)
| Method | Unfulfilled only | Fulfilled only | Partly fulfilled (mixed) |
|---|
| A Together | Ships all unfulfilled units with the same tracking number | “Overwrite existing tracking” ON: overwrite (if several, let the user choose). OFF: not applied | Stops and lets the user choose on the confirmation screen |
| B Per product | Partially ships only the row’s product. If it does not match, stop that order. If there is no history and there are several rows, stop and ask to export the CSV first | ON: overwrite the fulfilled unit that contains the row’s product. OFF: not applied | Products on the unfulfilled side are partially shipped. For rows of products on the fulfilled side: overwrite if ON, not applied if OFF |
| C Per fulfillment unit | With the “combine” setting, combine into one; with the “same number for each unit” setting, ship each unit with the same number | ON: overwrite. OFF: not applied | Stops and lets the user choose on the confirmation screen |
- “Unfulfilled only” includes the state where unfulfilled units were recreated after a shipment was cancelled.
- In a template that splits every row so that an order expands into several rows, even if the upload has only one row, an order that is unfulfilled only stops (so as not to ship several units by mistake).
PROC-TU1 Upload a CSV and reflect the tracking numbers
Where: App left menu "Order List" > top tab "Update tracking"
Prerequisite: import the exported CSV into the carrier's system and download the CSV that includes the tracking numbers
Steps:
1. Open the top tab "Update tracking"
2. Upload the CSV with "Select file" ("Click or drag and drop")
3. Check "Template" and "Shipping carrier" (the carrier is shared with "Shipping carrier (tracking update)" in the template's Basic info; changing either changes the same value). When you switch "Template", the settings below change to that template's content
4. In "How to read the CSV (columns)" check "Order ID column", "Tracking column" and the encoding.
For a CSV with a header row, check "Treat the first row as header" ("1 行目をヘッダーとする")
5. Check the "Apply options" (below). To change the tracking number of an order that already has one (a shipped order), turn ON "Overwrite tracking numbers on already-applied orders" (it is not saved in the template, so set it each time. If it stays OFF, shipped orders are "Not applied")
6. In "Preview", check each row's action ("Update", "Overwrite", "Not applied", etc.) and its reason
7. "Update tracking numbers" → confirm ("Update tracking numbers?") → "Apply"
Result: the "Update finished" screen shows the applied orders, the rows not applied and the failed rows
Apply options
"Notify customer(s) of shipment" … when ON, a shipment notification email with the tracking number is sent to the customer (OFF is the safe way to try)
"Add order tags when applying" … when you enter "Tags to add", the applied orders get the tags (example: shipped)
"Split fulfillment of shipments" … when ON, if one order is exported split into several rows, Shopify's fulfillment is split so that each row's tracking number can be applied. One value shared by all templates.
Cannot be used in templates where "Split per quantity" or "Export split by delivery fulfillment unit" is chosen (cannot be combined)
"Record only the completion of the fulfillment (do not register a tracking number)" … when no tracking number is needed, such as in-house shipping or delivery-box shipment. The tracking column becomes disabled
"Overwrite tracking numbers on already-applied orders" … when ON, replaces the tracking number of already fulfilled orders with the CSV value. Includes orders fulfilled by other apps or manually. It is not saved in the template
Main displays on the confirmation screen
| Display | Meaning |
|---|
| Update / mark as fulfilled | Ships the unfulfilled unit and registers the tracking number |
| Overwrite / overwrite tracking number | Replaces the fulfilled tracking number with the CSV value (when “Overwrite existing tracking” is ON) |
| Not applied (“Rows that will not be applied”) | Rows skipped with a reason. Example reasons: no history / the product cannot be decided / fulfilled and overwrite OFF / no such order |
| The fulfillment unit cannot be identified | It is not decided which unit the row corresponds to. Choose on the selection screen, or review the settings (split) |
| Needs checking — orders that need a retry | A fetch or update failed temporarily. Retry |
| Empty tracking — existing erased | The CSV tracking number is empty and overwrite is ON, so the existing tracking number will be erased. Do not execute if this is not intended |
| Blank / no order / match | A row with an empty tracking number / no order matches the CSV’s order number / a row matched to an order |
QA
- Q: Even after uploading, it is “not applied”. A: Ask them to look at the reason in “Rows that will not be applied” on the confirmation screen. Common reasons are (1) no history (the CSV was not exported first), (2) fulfilled and “overwrite” is OFF, (3) the product cannot be decided, (4) a wrong order ID column (ESCALATE).
- Q: I want to correct the tracking number of a fulfilled order. A: Turn ON “Overwrite tracking numbers on already-applied orders” and upload (TU-1; orders fulfilled by other apps or manually are included).
- Q: I want to ship only some items first and the rest later. A: Turn ON “Split fulfillment of shipments”, export with a template where you can specify the product per row, and upload (method B). Several rows without history stop, so export the CSV first.
- Q: The tracking number was erased / overwritten with empty. A: If a row with an empty tracking number is uploaded with overwrite ON, the existing number is erased (the confirmation screen shows “Empty tracking — existing erased”). Do not execute if not intended. Do not assert; check the order number and the screen at execution (ESCALATE).
- Q: An email went to the customer / I do not want emails sent. A: It follows the “Notify customer(s) of shipment” setting (TU-5). OFF when trying.
- Q: It says the order ID column and the tracking column are the same. A: The column numbers point to the same column (TU-7). Check the CSV’s columns and specify another column.
- Q: The characters are garbled and the orders are not found. A: Check that “Character encoding” matches the CSV. Many carriers’ CSVs are Shift_JIS (TU-6).
- Q: How many can be uploaded? A: There is no limit, but fetching takes time as the count grows. Since it is processed in the browser, 200 or fewer is recommended (human-facing FAQ).
ESCALATE
Reflecting tracking numbers changes real orders. In the following cases, do not state a conclusion; check the situation.
| Situation | Information to request |
|---|
| The wrong order was marked as shipped / shipped twice | Order number, date and time of execution, the template name used, the apply options (overwrite / split / notify), a screenshot of the confirmation screen |
| Not reflected / skipped | Order number, the reason in “Rows that will not be applied” on the confirmation screen, that row of the CSV (hide personal data), template name |
| The tracking number disappeared | Order number, the screen at execution, the “overwrite” setting, the value of the CSV’s tracking column |
| The fulfillment unit cannot be identified / needs checking | Order number, the state of the “Unfulfilled” and “Fulfilled” cards in Shopify’s order detail, the template’s split setting |
| Used together with another app and the result does not match | The names of the apps used together, which one shipped |
SEE
