CSV Export: Output Value Settings (Default Value, Conditional Branches, Conversion, Code)

plan: Pro plan only (R6)
screens: "Settings" → "CSV templates" → "Edit" of a template → "Field definitions" → "Edit" of a column (the value edit screen)
verified_from: The CSV screen implementation (value edit screen, output engine, token definitions) + human-facing manual
ui_verified: Field names were confirmed from the code. Visual confirmation on the real screen has not been done
note: Some order-info item names are shown in Japanese in the English admin. They are written here as the Japanese name plus an English gloss.
related: For the basics of CSV order export see [Pro: CSV order export basics](/en/cc-delivery-date-time/ai/090/csv-basics/)

SUMMARY

The value of one CSV column (one “field”) is decided in three layers: A Default value → B Conditional branches (exceptions) → C Output constraints. For each order, B is evaluated from the top and the value of the first matching branch is used. If none match, A is used. Finally C (the character limit) is applied.

How a value is decided

V-1  Screen structure: the "edit value" screen has three layers.
       A "Default value" … the value used for all orders that match no branch
       B "Branches — exceptions" … evaluated from the top; the value of the first matching branch is adopted. If none match, A
       C "Export" … "Field name" (the column name in the CSV header row) and "Max chars". Applied last to the result of either A or B
V-2  There are two ways to build the value of A:
       "Fixed" … output the same string on every row (example: waybill type "0"). It is not interpreted as order information
       "Detail (order info, code)" … line up one or more of order information, free-typed text and code, and combine them into one cell with a separator
V-3  A line in "Detail" has three kinds: order information (token) / free input (the typed text is output as it is) / code (JavaScript).
V-4  When several lines are lined up, they are joined with "joined by" ("Separator (be)"). The default separator is a comma.
V-5  Only when the "Order info" line is date-type (delivery date, delivery time, order creation date, ship date, Today±N, "Attribute: Key name"),
     "Date format" can be specified (example: YYYY-MM-DD / YYYY/MM/DD / YYYY年M月D日). Only strings that can be converted to a date are formatted.
V-6  "Replacement rules" can be attached only to an "Order info" line (not to free-input or code lines). Several can be added with "Add replacement rule",
     and "Regular expression" lets you use a regular expression for the string before conversion. An invalid regular expression is treated as a literal string.
V-7  For data that has both a fixed value and a Detail value, the Detail (selectVal) takes priority and the fixed value is ignored.
V-8  "Max chars" is the maximum number of characters of the output string. Empty means unlimited.
V-9  A column shown as "Value set by branches" is a column where A is empty and the value is decided only by the branches.

Main items selectable in “Order info”

On the screen they are divided into the groups “order”, “Customer / Shipping”, “Billing”, “Products”, “Amount”, “Date / Attributes” and “Order attributes (customAttributes)“. Many item names are shown in Japanese; the Japanese name is given with an English gloss.

GroupMain items (display name on the screen)
orderOrder number, order number-ID, Shopify Order ID, order tags, E-mail, order note, discount codes, payment gateway (payment method) name, payment status, fulfillment status, list of excluded product titles
Customer / ShippingPhone number, delivery method, shipping title, shipping recipient first name (配送先氏名(名前)), last name (配送先氏名(苗字)), company, phone, postal code (配送先郵便番号), address, address 1 / 2, country (English)
BillingBilling company, name, phone, postal code, address, address 1 / 2, country
ProductsProduct name, product tags, SKU, variant ID, unit price, line amount (after discounts), quantity ordered, quantity to be fulfilled, line item properties
AmountTotal weight (g), total price, discount amount, total shipping, total tax, subtotal, store credit used, etc. (with items in each currency)
Date / AttributesDelivery Date (App), Delivery Time (App), Delivery method (App), Ship date (App), order creation date, Today-1 / Today+0 / Today+1 / Today+2
Order attributesAdditional details Key / Value, and “Attribute: Key name” for which you specify the Key name on the screen
  • Items such as “Delivery Date (App)” are the delivery date and time that this app wrote with the widget (the order’s “Additional details”).
  • “Discount Codes” are the discount codes used on the order. When there are several, they are joined with the column’s separator (be), the same as tags (”, ” in code variables and judgment targets). Orders without a code are blank. The name of an automatic discount (no code) cannot be output.
  • With “N days from today (custom)” you can specify any number of days for Today+N (negative for the past).
  • Metafields registered in “Order Metafields” under “Settings” → “Fetch settings” appear as options named “Metafield[namespace.key]“. A key that is not registered is not fetched, so it cannot be selected. Fetch again after registering. The same options appear as the target of a conditional branch.

How to build a conditional branch (B)

Form: "If the order's [Field] [method], [value to output]"
Field: the same items as order information (shipping address, product name, product tags, order tags, total price, total weight, Key of additional details, etc.)
Method:
  String … "contains", "does not contain", "contains any", "contains none" (separate several words with commas)
  Number … "Number range (min–max)" (total price, total weight, quantity, etc.)
  Date   … "Date range (YYYY-MM-DD)"
AND   : adding a condition with "Add condition (AND)" makes it match only when all conditions are met
Value to output: Fixed / Detail (order info, code) / "Matched value (value of the tested field)"
Evaluation order: from the top. The first matching branch is adopted (change the order by reordering)

PROC-V1 Output a fixed value (example: always “0” for the waybill type)

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps:
1. "Settings" → "CSV templates" → "Edit" of the target template
2. In "Field definitions", press "Edit" of the target column
3. In A "Default value" choose "Fixed" and put the value into "Fixed string"
4. "Save" → "Save" at the top of the screen

PROC-V2 Output order information / join several values (example: surname and given name in one cell)

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps:
1. "Edit" of the column → choose A "Detail (order info, code)"
2. On the first line choose the last name of the shipping recipient (配送先氏名(苗字))
3. Add a second line with "Add value (combine)" and choose the first name (配送先氏名(名前))
4. In "Separator (be)" put the connecting character (a half-width space or empty)
5. Save

PROC-V3 Replace characters (example: +81 in a phone number to 0)

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps:
1. "Edit" of the column → in A "Detail" choose the "Phone number" (etc.) line
2. Press "Add replacement rule" under that line
3. Put "+81" as the string before conversion and "0" after conversion
4. To replace with a regular expression, check "Regular expression"
Notes:
- To put characters in when the value is blank (no value), leave "before" empty and specify the characters in "after" (described in the human-facing manual)
- Replacement can be attached only to "Order info" lines. Not to free-input or code lines (V-6)
- Splitting a postal code (first 3 digits / last 4 digits) or a phone number is done with a regular-expression replacement. For concrete examples see the human-facing manual "Character conversion of output values (regular expressions)"

PROC-V4 Change the value by condition (example: change the cool-delivery class for orders containing frozen food)

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps:
1. "Edit" of the column → in B "Branches — exceptions" press "Add branch"
2. For "Field" choose "product tags" (or product name), for the method "contains" / "contains any", and as the value "Frozen" etc.
3. Enter the value to output (example: the cool-delivery class value)
4. The default value of A is the value for orders that match none
5. Save
Notes:
- Branches are evaluated from the top and the first match is used. Check the order
- To match only when several conditions are all met, use "Add condition (AND)"

PROC-V4a Make all the sender columns gift-ready at once

Where: left menu "CSV" > top tab "Settings" > "CSV templates" > "Edit" on the template > "Basic info" on the right
Prerequisite: the template's "Carrier" (type) is not "Not specified"
Steps:
1. Press "Make the sender gift-ready (N columns)". A modal opens listing each sender column and the billing value it will use
2. Check it and press "Apply all" (press "Cancel" to stop)
3. Press "Save" at the top of the screen
Notes:
- Only the sender columns (columns named like the carrier's preset) are changed. Columns that already have the gift branch are left as they are
- When every sender column is already gift-ready, this button is not shown
- To choose different values per column, use PROC-V4b ("Add from template" per column) or edit the column's branch

PROC-V4b Output the billing value only when billing and shipping differ (the sender of a gift order)

Where: left menu "CSV" > top tab "Settings" > "CSV templates" > "Edit" of the template > "Field definitions" > "Edit" of a sender column
Prerequisite: the template's "Carrier" (type) is not "Not specified" (otherwise the button does not appear)
Steps:
1. In A "Default value", enter your own information (sender name, address, phone number, etc.)
2. In B "Branches — exceptions", press "Add from template". A card opens
3. Choose "Billing value to use" (Name / Phone / Postal code / Address / Address 2). If the column name is still the preset one such as "ご依頼主名", it is already selected. For a renamed column, choose it yourself
4. Press "Add". One branch is added (when "Billing address matches shipping address" contains "false", the billing value is output)
5. Repeat per column, then "Save" and "Save" at the top of the screen
Notes:
- Orders whose billing and shipping addresses are the same keep the A default value. If the billing address lacks the item, the cell is left empty
- The added branch is an ordinary conditional branch. The combination of values and character conversion can be changed with "Edit" in the list
- A column that already has the gift branch shows "Added" and cannot get a second one

PROC-V5 Output the delivery date and delivery time

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps:
1. "Edit" of the column → A "Detail" → choose "Delivery Date (App)" in order information ("Delivery Time (App)" for time)
2. Specify the date format ("Date format": YYYY-MM-DD, etc.)
3. Save
Note: for orders with no delivery date and time (for example dynamic checkout) the cell is empty.
     To fill in the delivery date and time afterwards for an order, there is a way using metafields (human-facing manual "Output settings for order metafields")

PROC-V6 Build a value with code (JavaScript)

Where: App left menu "Order List" > top tab "Settings" > "CSV templates" > "Edit" of the target template > "Field definitions" > "Edit" of the target column
Steps: "Edit" of the column → A "Detail" → set the line type to "Code (JavaScript)" and write JavaScript.
      "Edit code with debugger" lets you check the run result against a sample order
How to write:
- Refer to the order information with the order object. The code is an "expression", and the result of that expression is the output value (example: `order.shippingAddress.formattedArea`)
- A single-line expression can be written as is. Code spanning multiple lines (for example, using `const`) must be written as an immediately-invoked function `(() => { ... return value; })()`; without it the correct value is not output (sample in the human-facing manual)
- For date calculation, `dateCalculate(date, days, "YYYY/MM/DD")` can be used. Example: `dateCalculate(order.date, -5, "YYYY/MM/DD")` (5 days before the delivery date), `dateCalculate(new Date(), 5, "YYYY/MM/DD")` (5 days from today). The format is the day.js format
- The result of `dateCalculate(order.date, …)` depends on what the order has as its desired delivery date. For an order whose desired delivery date is a date, the date calculated from it is output. For an order whose value is a string such as "No Request" ("指定しない" / "指定なし"), it cannot be read as a date, so an empty string (blank) is output. For an order with no desired delivery date at all (no value), the date **calculated from today's date** is output; it does not become blank. To give such orders a different value, add a branch in the conditional branches of B (PROC-V4) with the target field "Delivery Date (App)" and an empty value. If the code causes an error, an empty string is output.
- Use const / let for variable declarations (do not use var)
- On an error the cell is empty (the export does not stop)
Caution (pitfalls in behavior):
- If the string "customAttribute" is written as it is in the code, the code is not executed and a string joining all the items of "Additional details" is output.
  Workaround: split the string. Example: const ATTR = "custom" + "Attributes"; const attrs = Array.isArray(order[ATTR]) ? order[ATTR] : [];
- For an order that does not have the metafield, order.metafields itself is undefined. Refer to it with ?. as in order.metafields?.['namespace.key'].
  (Plain access throws an exception and that row becomes empty)

QA

  • Q: I want to split the postal code into the first 3 and last 4 digits. A: Split the “postal code” into two columns and set the replacement rules with regular expressions. For the example see the human-facing manual “Character conversion of output values (regular expressions)” (PROC-V3).
  • Q: I want “+81” in a phone number to be “0”. A: PROC-V3.
  • Q: I want the prefecture and the city in separate columns. A: Output the prefecture with a conditional branch (B) per prefecture. For the city, remove the leading prefecture with a regular expression in a replacement rule (an example in the human-facing manual: replace ^(.{2}[都道府県]|.{3}県) with empty).
  • Q: I want to switch the carrier or a value by condition. A: Switching a value is the conditional branch of B (PROC-V4). Switching the template itself is done with “Routing rules” (another page).
  • Q: For gift orders I want the sender to be the billing address. A: PROC-V4a for all columns at once (“Make the sender gift-ready” in Basic info), or PROC-V4b per column. Use “Add from template” in B and add the billing value to use. The steps are also in the human-facing manual (/blogs/csv-gift/, Japanese only).
  • Q: I want to output with a formula, such as a total calculation. A: Calculate it with code (JavaScript) (PROC-V6). For cautions such as treating a missing value as 0, point to the human-facing manual.
  • Q: I want to output a metafield value. A: Register the metafield key in “Fetch settings”, fetch again, then choose the key under “metafield” in order information. An order that does not have it gives an empty cell (caution in PROC-V6).
  • Q: The code does not work and a long string of attributes is output. A: Check whether the code contains the string “customAttribute” (the pitfall in PROC-V6).
  • Q: I want to output the line item properties of a product. A: Line item properties are per-product information, so the human-facing manual’s procedure is to turn ON “split rows per product” and then specify the property’s Key. Guide the actual steps on the screen after seeing the store (ESCALATE).

ESCALATE

SituationInformation to request
A column’s value is not as expected / is emptyTemplate name, column name, the expected value, the target order number, a screenshot of that column’s settings (A, B, C)
A regular expression / code does not workThe code or regular expression itself, the actual value of the item in the target order, the error shown
Line item properties / metafields do not appearThe key name set, a screenshot of the order’s “Additional details” / metafield, the “Fetch settings” screen
Want to match a carrier’s specified formatCarrier name, specification of the import format (number of columns, column order, required fields, encoding). It is an individual design, so draft an inquiry to the developer

SEE

Install