WooCommerce settings

Every setting on the WooCommerce Orders, Shipments, Inventory, Credits, Products and Customer Update Configurations, what each does and when to change it.

The WooCommerce connector imports orders and credits from your store, sends shipments and stock levels to it, and can import or send products and send customers. Each Document type has its own Configuration: Orders (WooCommerce Order), Shipments, Inventory, Credits, Products (WooCommerce Product Update) and Customer Update. The settings for each are below.

Orders: dates and which orders

Setting	What it does	Values / default	When to change it
Setup date `setupDate`	Only orders created on or after this date are imported, so historical orders aren't pulled in at go-live.	Date. Set automatically when the Integration is first configured.	Not normally changed afterwards.
Last import date `lastImportDate`	The import watermark. Each run only fetches orders modified after it.	Date and time. Managed by the system.	Don't edit it by hand.
Statuses to import `statusesToImport`	The WooCommerce order statuses to import.	List. When empty, no orders are imported.	Always set it: list the statuses your team should fulfil.
Require date paid `requireDatePaid`	Skips orders that have no `date_paid` value in WooCommerce, so only paid orders are processed.	`true` or `false`.	Turn on if unpaid orders can reach an imported status.

Orders: customers

Setting	What it does	Values / default	When to change it
Default customer `defaultCustomerId`	The Party used when an order has no identifiable customer.	A Party ID.	Set it as a safety net.
Always use the default customer `alwaysSetDefaultCustomerId`	Uses `defaultCustomerId` for every order, whether or not a customer could be identified.	`true` or `false`.	Turn on when all orders should go to one generic customer account.
Guest customer `guestPartyId`	The Party for guest checkout orders (WooCommerce customer ID `0`), so guest purchases are tracked separately from registered customers.	A Party ID.	Set it if your store allows guest checkout.
Billing email as identifier `includeBillingEmailAsCustomerIdentifier`	Adds the billing email as a customer identifier of type `woo-commerce-billing-email`, for matching by billing email.	`true` or `false`.	Turn on when customers are best matched by email.
Customer identifier metadata key `customerIdentifierMetaDataKey`	A WooCommerce metadata key whose value is used as the customer identifier for matching.	A metadata key.	Set it when a plugin stores the customer's account code on the order.
Continue if the identifier is missing `continueIfCustomerIdentifierMetaDataMissing`	Carries on importing when the `customerIdentifierMetaDataKey` metadata is absent. When `false`, orders without it are rejected.	`true` or `false`.	Turn on if some orders legitimately have no identifier (guests, for example).

Orders: lines, discounts and values

Setting	What it does	Values / default	When to change it
Coupon types to process `couponTypesToProcess`	The WooCommerce coupon types applied as order-level discount adjustments.	List of coupon types.	List only coupon types whose discount isn't already in the line prices, or the discount is counted twice.
Metadata line adjustments `metadataLineAdjustments`	Turns WooCommerce order metadata values into adjustments (charges or discounts).	List of entries; fields below.	Use it when a plugin records fees or discounts as order metadata.
Quantity information `quantityInformation`	Adjusts line quantities using a metadata value: a regex pattern to match the metadata, the metadata key to read the multiplier from, a `divide` flag (when `true`, the multiplier is inverted) and a `skuRegexPattern` to limit which lines it applies to.	Optional object.	Use it when a plugin sells packs or cases and records the multiplier in metadata.
Try to determine tax inclusion `tryDetermineTaxInclusion`	Tries to work out from the WooCommerce data whether prices include or exclude tax.	`true` or `false`.	Turn on if tax totals aren't coming out right.

Fields for each metadataLineAdjustments entry:

Field	What it does
`metadataKey`	The WooCommerce metadata key to read
`metadataCurrencyKey`	Optional. A metadata key holding the currency for this adjustment
`productName`	The display name of the adjustment
`sku`	Optional. A SKU for the adjustment line
`isCharge`	`true` for a charge, `false` for a discount

Orders: delivery, notes and extra data

Setting	What it does	Values / default	When to change it
Default fulfilment location `defaultFulfillmentLocationId`	The warehouse assigned to every imported order.	A Location ID.	Set it to the warehouse that fulfils store orders.
Earliest ship date metadata key `earliestShipDateMetaDataKey`	The metadata key the earliest ship date is read from.	A metadata key.	Set it when a delivery-date plugin records a ship date.
Earliest ship date format `earliestShipDateMetaDataFormat`	The format used to read that date, in .NET format string syntax.	For example `"yyyy-MM-dd"`.	Set it to match how the plugin writes the date.
Customer note in shipping instructions `storeCustomerNoteInShippingInstructions`	Puts the customer's order note into the shipping instructions field, so delivery notes are kept.	`true` or `false`.	Turn on if customers leave delivery notes at checkout.
Note metadata items `noteMetadataItems`	Metadata keys whose values are appended to the order notes.	List of metadata keys.	Use it to surface plugin data in the notes.
Shipping line metadata `shippingLineMetadata`	Metadata keys read from WooCommerce shipping lines and included in the imported data.	List of metadata keys.	Use it when a shipping plugin stores useful data on the shipping line.
Metadata parse items `metaDataParseItems`	WooCommerce metadata records to parse and include in the imported Document.	List.	Use it to bring specific metadata fields into the order data.
Document tag generation `documentLevelTagGeneration` / `documentLevelAdvancedTagGeneration`	Rules that tag orders automatically from order attributes, for classification and routing.	Lists of rules.	Use them to tag or route orders by any order attribute.

Shipments

These settings are on the Shipments Configuration.

Setting	What it does	Values / default	When to change it
Use Shipment Tracking `useShipmentTracking`	Records tracking with the WooCommerce Shipment Tracking plugin.	`true` or `false`. When off or not set, tracking is recorded as a standard WooCommerce order note.	Turn on if the store has the Shipment Tracking plugin enabled.

Inventory

These settings are on the Inventory Configuration.

Setting	What it does	Values / default	When to change it
Maximum products per file `maximumProductsPerFile`	Splits the inventory update into several Documents of at most this many products.	A number.	Set it for a large catalogue, to avoid oversized Documents.
Fail on missing products `failOnMissingProducts`	Fails the whole inventory update if any product isn't found in WooCommerce.	`true` or `false`. When `false`, missing products are skipped.	Leave off unless every product must exist in the store.

Credits

These settings are on the Credits Configuration.

Setting	What it does	Values / default	When to change it
Setup date `setupDate`	Only credits created on or after this date are imported.	Date. Set automatically when the Integration is first configured.	Not normally changed afterwards.
Last import date `lastImportDate`	The import watermark for credits.	Date and time. Managed by the system.	Don't edit it by hand.
Import delay `importDelay`	A wait before a credit is imported, so other systems can make their changes first.	Duration, for example `00:05:00` for five minutes.	Set it when refunds are edited just after they're made.
Disable the expected payable tag `disableExpectedPayableTag`	Stops the expected payable tag being added. That tag normally checks that the calculated total matches the expected amount.	On or off.	Only to skip the total check; investigate a mismatch first.

Products

These settings are on the Products (WooCommerce Product Update) Configuration.

Setting	What it does	Values / default	When to change it
Setup date `setupDate`	Only product updates on or after this date are processed.	Date. Set automatically when the Integration is first configured.	Not normally changed afterwards.
Last import date `lastImportDate`	The import watermark for product updates.	Date and time. Managed by the system.	Move it back once to re-read the catalogue, for example after setting `variationNameFormat`.
Import delay `importDelay`	A wait before a product update is imported, so other systems can change the product first.	Duration, for example `00:05:00`.	Set it when products are edited in several steps.
Variation name format `variationNameFormat`	How a variation's name is built on import, using placeholders (below).	A format string. When not set, a variation keeps the name WooCommerce gives it, or its parent's name if it has none.	Set it when variation names from WooCommerce aren't consistent.
Keyed price metadata map `keyedPriceMetadataMap`	Maps keyed price keys to WooCommerce product metadata keys, to read or write prices in product metadata.	Dictionary.	Use it when a pricing plugin stores prices in metadata.
Keyed price as regular price `useKeyedPriceAsRegularPrice`	Uses the price stored under this keyed price key as the WooCommerce regular price instead of the standard price.	A keyed price key.	Set it when the store should show a particular price list.
Keyed price as sale price `useKeyedPriceAsSalePrice`	Uses the price stored under this keyed price key as the WooCommerce sale price.	A keyed price key.	Set it to push a promotional price list.
Price as sale price `usePriceAsSalePrice`	Writes the standard product price as the sale price instead of the regular price.	`true` or `false`.	Turn on to show the price as a promotional price.
Default status `defaultStatus`	The status given to products newly created in WooCommerce.	Default `draft`. Values include `draft` and `publish`.	Keep `draft` so new products are reviewed before they go live.
Rate limit `rateLimitPermitLimit` / `rateLimitWindow`	How many requests can be made to WooCommerce within a time window, to stay inside its API limits.	A number of requests and a window.	Lower them if the store's host throttles requests.
Update only `updateOnly`	Updates existing products only; new products aren't created.	`true` or `false`.	Turn on to sync prices or details without adding products to the store.
Disabled field mappings `disabledFieldMappings`	Fields set to `true` aren't written when products are sent, so values maintained in WooCommerce are kept.	Dictionary of field names (below).	Use it to protect names, descriptions or prices maintained in the store.

Variation name placeholders

Placeholder	Value
`{0}`	The parent product's name
`{1}`	The variation's own name, as WooCommerce returns it
`{2}`, `{3}`	The first attribute's name and value, for example `Size` and `Small`
`{4}`, `{5}`	The second attribute's name and value
…	And so on for each further attribute

For example, "{0} - {3}" names the Small variation of Latex Gloves - 10 Box Case as Latex Gloves - 10 Box Case - Small, and "{0} ({2}: {3}, {4}: {5})" gives Nail Polish (Colour: Red, Size: Large).

Attributes are ordered by WooCommerce attribute ID. A global attribute (set up under Products → Attributes) has a fixed ID, so a placeholder names the same attribute on every product. An attribute typed on a single product has ID 0; those come first, in name order.
Only attributes the product varies by are included, not descriptive ones such as a brand.
Prefer {0} and the attribute values over {1}: what WooCommerce puts in a variation's own name differs between stores.
The format only applies when every placeholder it uses has a value. Otherwise the variation keeps the name it would have had. An attribute set to "Any" is left out, which moves every later attribute up one pair.
An invalid format (an unclosed {, for example) fails the import with an error, and lastImportDate doesn't move.
Only variations imported after you set it are renamed. A variation is read only when its parent changes, so to rename the existing catalogue, move lastImportDate back once.

Product fields you can disable

Fields not listed are enabled, so an empty dictionary maps everything. Names are matched ignoring case. A disabled field is left out of the payload entirely, so WooCommerce keeps what it holds.

Field	Covers
`name`	The product name
`description`	The product description
`regular_price`	The regular price, including the value chosen by `useKeyedPriceAsRegularPrice`
`sale_price`	The sale price from `usePriceAsSalePrice` and `useKeyedPriceAsSalePrice`
`weight`	The product weight, converted to kilograms
`tax_class`	The product tax class
`meta_data`	The product metadata written by `keyedPriceMetadataMap`

The SKU can't be disabled: it's how an existing product is found before it's updated.

Customer updates

These settings are on the Customer Update Configuration, which sends customers to WooCommerce.

Setting	What it does	Values / default	When to change it
Username identifier type `usernameIdentifierTypeId`	The identifier type used to match WooCommerce usernames to Parties.	An identifier type ID.	Set it so customers can be found and updated by username.
Create customers `createEnabled`	Creates customers that don't yet exist in WooCommerce.	`true` or `false`. Default `true`. When off, customers not found are skipped.	Turn off if accounts are only ever created on the website.
Update customers `updateEnabled`	Updates customers that already exist in WooCommerce.	`true` or `false`. Default `true`. When off, existing customers are left alone.	Turn off to create new customers only.
Subscription metadata key `subscriptionMetadataKey`	The WooCommerce customer metadata field written from the customer's payment term. This switches the whole payment-term feature on: leave it empty and no `meta_data` is sent, whatever the term lists hold.	A metadata key.	Set it when the storefront needs to know which customers buy on account.
Subscription identifier type `subscriptionIdentifierTypeId`	The identifier type whose value is written to the subscription field for customers on a credit term.	An identifier type ID. Default `unleashed-customer-code`.	Change it if a different identifier should be written.
Credit payment terms `creditPaymentTerms`	Customers on one of these terms have their identifier written to the subscription field. If the identifier can't be found, no metadata is sent rather than an empty value (which would read as an upfront customer).	List of payment terms, for example `["30 Days"]`.	List your account terms.
Upfront payment terms `upfrontPaymentTerms`	Customers on one of these terms have the subscription field cleared: it's sent with `""` as its value, not removed.	List of payment terms.	List your pay-upfront terms.
Disabled field mappings `disabledFieldMappings`	Fields set to `true` are left unchanged when an existing customer is updated, so values maintained on the website aren't overwritten.	Dictionary of field names (below).	Use it to protect, for example, the customer's login email.

Both term lists are matched ignoring case and surrounding whitespace. A term in neither list, or a customer with no payment term, is sent no metadata, so a value set by hand on the site is never overwritten. A term in both lists is treated as credit.

Customer fields you can disable

Fields not listed are enabled, so an empty dictionary updates everything. Names are matched ignoring case.

Field	Covers
`email`	The customer's account email
`first_name`	The customer's first name
`last_name`	The customer's last name
`billing`	The whole billing address, including the billing email and phone
`shipping`	The whole shipping address
`meta_data`	The subscription metadata written from the payment term

These apply to updates only. A new customer is always created with every field, because WooCommerce needs an email to create one.
An update with every field disabled, or with only meta_data enabled and no metadata to send, is skipped.
The customer's ID and username can't be disabled: they're how an existing customer is found.

To update only the subscription metadata when a payment term changes:

"disabledFieldMappings": { "email": true, "first_name": true, "last_name": true, "billing": true, "shipping": true }