Skip to main content

WooCommerce Connections and Settings

The subscription settings for the iPaaS.com WooCommerce integration: what each one does, its default, the scopes and webhooks it registers, and how they affect runtime behavior.

Integrate iPaaS.com with WooCommerce to enable seamless data synchronization for products, product variants, stock, orders, refunds and customers.

This document describes every subscription setting the WooCommerce integration exposes. It also covers authentication, the connection test, the scopes the integration registers, the webhooks it registers in WooCommerce, and the values it stores. It is the reference companion to the WooCommerce Installation Instructions.

How to Connect

Prerequisites

Before you set up the WooCommerce integration in iPaaS.com, make sure that:

  • The store is served over HTTPS. An address starting with http:// is refused.

  • WordPress permalinks are set to any option other than Plain (in WordPress, Settings > Permalinks). WooCommerce's REST API needs readable permalinks.

  • A WooCommerce REST API key exists with Read/Write permissions, for an administrator. Create it in WordPress under WooCommerce > Settings > Advanced > REST API keys. See the WooCommerce REST API guide and the WooCommerce Installation Instructions for the steps.

  • The web server passes the Authorization header through to WordPress, and any firewall, security plugin or cache in front of the store lets requests to /wp-json/wc/v3/ reach WooCommerce (reading and writing).

Configuration Details

  • Store URL: your store's home address, as it appears in the browser address bar. Example: https://shop.example.com

  • Consumer Key: the Consumer key of the REST API key. It starts with ck_. Example: ck_0123456789abcdef... (an example, not a real key)

  • Consumer Secret: the Consumer secret of the same key. It starts with cs_ and is shown only once, when the key is created. Example: cs_0123456789abcdef... (an example, not a real key)

Configure Subscription Settings

The nine settings below appear on the iPaaS.com subscription page for the WooCommerce integration, in this order.

The WooCommerce Subscription Settings page with example values

Field

Description

Required

Example

Store URL

The store's home address. The integration calls the WooCommerce REST API under it.

Yes

https://shop.example.com

Consumer Key

The Consumer key of the WooCommerce REST API key (a password field).

Yes

ck_...

Consumer Secret

The Consumer secret of the same key (a password field).

Yes

cs_...

Stock Locations

The iPaaS.com locations whose stock counts toward the WooCommerce stock number. Blank counts every location.

No

Main Warehouse, Downtown Store

Stock Quantity Field

Which iPaaS.com quantity counts: QtyAvailable (default) or QtyOnHand. A list of these two values.

No

QtyAvailable

Order Page Size

Orders read per page by the order poll. Default 50, at most 100.

No

50

Order Poll Initial Days

How many days back the first order poll looks. Default 7.

No

7

Customer Page Size

Customers read per page by the customer poll. Default 50, at most 100.

No

50

Customer Poll Initial Days

How many days back the first customer poll looks for new customers. Default 7.

No

7

Store URL

Item

Value

Required

Yes

Data type

String

Default

(empty)

Your store's home address, for example https://shop.example.com. The integration calls [Store URL]/wp-json/wc/v3.

  • A bare address such as shop.example.com gets https:// added.

  • An address starting with http:// is refused with WOOC-VALD-1003. Serve the store over HTTPS.

  • A trailing /, and a pasted /wp-json or /wp-json/wc/v3, are removed. Anything after ? or # is ignored.

  • A store in a sub-folder works: https://example.com/shop calls https://example.com/shop/wp-json/wc/v3.

  • A port number is kept.

  • An address copied from the WordPress admin (containing /wp-admin/… or ending in /wp-login.php) is accepted: that part is removed, so the store's own address is used.

  • If the store's address changes when you open it in a browser (for example to www.), enter the address the browser ends on.

Consumer Key

Item

Value

Required

Yes

Data type

Password

Default

(empty)

The Consumer key of the WooCommerce REST API key. It starts with ck_. Create it in WordPress under WooCommerce > Settings > Advanced > REST API keys. See the Installation Instructions for the steps.

Consumer Secret

Item

Value

Required

Yes

Data type

Password

Default

(empty)

The Consumer secret of the same key. It starts with cs_. WooCommerce shows it only once, when the key is created.

  • A blank Consumer Key or Consumer Secret stops the connection with WOOC-VALD-1004.

  • To rotate the key, create a new key in WooCommerce, paste both new values here, save the subscription, then revoke the old key in WooCommerce.

Stock Locations

Item

Value

Required

No

Data type

String

Default

(empty)

The iPaaS.com locations whose stock counts toward the WooCommerce stock number. Core WooCommerce keeps one stock number per product (or per variation), so the integration adds up the quantities of these locations.

  • Leave it blank to count every location.

  • List iPaaS.com location ids or location names, separated by commas (or semicolons), for example Main Warehouse, Downtown Store. Names are matched without regard to capital letters.

  • A stock change at a location that is not listed does not change WooCommerce.

  • Every entry is checked against iPaaS.com's list of locations. An entry iPaaS.com doesn't have stops the stock update with WOOC-NFND-1006.

  • If iPaaS.com returns no location list, the entries can't be checked; a record whose locations match none of the entries then stops with WOOC-NFND-1006.

  • In a company with 100 or more locations, a location name can't be proven missing, so a misspelt name is not caught. Use location ids in a large company.

  • When the setting is valid and a product has no stock at the listed locations, no stock is written for it. This is not an error.

  • Your company's locations, with their names and ids, are listed in iPaaS.com's location settings. If you can't find the list, your MiSP or iPaaS.com support can give you the names.

This setting applies to every stock update, with the product or stock-only. With an iPaaS.com connection, the integration adds up the listed locations among all of the product's (or variant's) inventory records in iPaaS.com, reading each quantity from iPaaS.com. The stock records need the parent id mapped (WOOC-VALD-1010). The location mapping is optional: a stock record without a mapped location is found in iPaaS.com by its inventory record. When iPaaS.com's inventory doesn't list the transferred location or inventory record yet, the update stops with WOOC-NFND-1007, nothing is written, and iPaaS.com tries the transfer again automatically. This setting, not a stock collection's filter, decides which locations count.

Stock Quantity Field

Item

Value

Required

No

Data type

List

Default

QtyAvailable

Which iPaaS.com quantity counts for each location, in every stock update.

Value

Rule

QtyAvailable

Count each location's available quantity (default).

QtyOnHand

Count each location's on-hand quantity.

With an iPaaS.com connection, every stock update (with the product or stock-only, for a product or a variant) reads the stock at every listed location from iPaaS.com and uses this field for each, so the total is always one measure. A product transfer and a stock-only update therefore count the same quantity.

Map the same quantity in the stock collections' StockQuantity mapping as this setting: QtyAvailable with the default (the default templates' value), QtyOnHand when you choose QtyOnHand. When you change this setting, change that mapping too, in all five collections that map it: Add/Update WooCommerce Product Inventory FROM iPaaS.com, Add/Update WooCommerce Product Variant Inventory FROM iPaaS.com, the two inventory child collections of Add/Update WooCommerce Product FROM iPaaS.com, and the inventory child collection of Add/Update WooCommerce Product Variant FROM iPaaS.com. The total always counts the quantity this setting names. The mapped quantity never changes the total: the integration compares it with that location's available and on-hand quantities in iPaaS.com to confirm that iPaaS.com's read already shows the change, so the check covers only the quantity you map. When the mapped quantity matches neither the location's available nor its on-hand quantity in iPaaS.com, a product or variant transfer still writes the total read from iPaaS.com and logs a warning, and a stock-only update stops with WOOC-BIZL-1008. Don't map a formula (for example a safety buffer) there: it never changes the total, and every stock-only update would stop.

WooCommerce stores stock as a whole number. A total with a fraction stops the update with WOOC-VALD-1009.

Order Page Size

Item

Value

Required

No

Data type

Number

Default

50

How many orders order/poll reads per page. WooCommerce allows at most 100, so a larger value is treated as 100. A blank, zero, negative or non-numeric value uses 50. The poll walks forward by modification date and makes at most 200 requests in one run. When more orders changed than that, the next poll continues from the newest change this one read.

Order Poll Initial Days

Item

Value

Required

No

Data type

Number (whole days)

Default

7

How far back the first order/poll looks, in days. After the first poll, each poll starts from the newest change the previous poll read, and this setting no longer applies. A blank, zero, negative or non-numeric value uses 7; use 1 for the shortest look-back. A value above 3650 (ten years) is treated as 3650.

To bring older orders in on a new subscription, raise this value before the first order/poll runs.

Customer Page Size

Item

Value

Required

No

Data type

Number

Default

50

How many customers customer/poll reads per page. WooCommerce allows at most 100, so a larger value is treated as 100. A blank, zero, negative or non-numeric value uses 50. The poll reads newest customers first and stops at the last customer it sent, reading at most 200 pages in one run. When a run stops at that limit, it saves a resume point and the next run continues below it, so no new customer is skipped.

Customer Poll Initial Days

Item

Value

Required

No

Data type

Number (whole days)

Default

7

On the first customer/poll, only customers who registered in the last this-many days are sent. Customers who registered earlier are not loaded until they change in WooCommerce (the integration has no first load). After the first poll, each poll sends customers with an id above the highest one it has seen, and this setting no longer applies. A blank, zero, negative or non-numeric value uses 7; use 1 for the shortest look-back. A value above 3650 (ten years) is treated as 3650.

Authentication Methods

Item

Value

Mechanism

HTTP Basic authentication over HTTPS: Consumer Key as the user name, Consumer Secret as the password, on every WooCommerce call

Key type

A WooCommerce REST API key with Read/Write permissions, for an administrator

OAuth flow

None

Token refresh

None. The key works until it is revoked in WooCommerce or its WordPress user loses access.

Plain HTTP

Not supported. A store address starting with http:// is refused, so the key never travels unencrypted.

Logging

The key is never written to a log. Anything shaped like a WooCommerce key, and every web address query string, is masked in error messages and logs.

Connection test

When the connection is established (at the start of a transfer), the integration first checks the settings:

  • Store URL is filled in (WOOC-VALD-1001), is a web address (WOOC-VALD-1002) and does not start with http:// (WOOC-VALD-1003);

  • Consumer Key and Consumer Secret are both filled in (WOOC-VALD-1004).

Then it makes one real, read-only call: GET /wp-json/wc/v3/products?per_page=1. The store must answer with a list of products (an empty list is fine).

Store answer

Result

A list of products

The connection succeeds.

401, or 403 with the code rest_forbidden or a woocommerce_rest_authentication code (the key was refused)

The connection fails with WOOC-AUTH-1001. The key is wrong or revoked, or the web server removes the Authorization header.

Any other 403 from WooCommerce

The connection fails with WOOC-AUTZ-1001. The key's user is not an administrator or shop manager. A Read only key passes this check, because the check only reads; its first write fails with WOOC-AUTZ-1001. After the connection check, every 403 except a woocommerce_rest_authentication code is WOOC-AUTZ-1001, rest_forbidden included.

A web page instead of data

The connection fails with WOOC-EXTN-1001. A firewall, security plugin, maintenance page or cache answered.

404, or no WooCommerce API at the address

The connection fails with WOOC-NFND-1001. WooCommerce is not active, the address is wrong, or permalinks are set to Plain.

No answer

The connection fails with WOOC-EXTN-1002.

A Store URL naming a different store from the one the subscription first connected to (the persistent value Linked Store)

The connection fails with WOOC-BIZL-1014 before anything is written: a different store needs its own subscription. The integration reads from that store first (the connection check and its webhook list) but never writes to it. The same store at a new address is recognised by this subscription's webhooks in it, and the new address is recorded. If none of its webhook scopes was on, delete Linked Store on the Subscription Settings page, then retry.

A redirect to another address

The connection fails with WOOC-EXTN-1003, naming the address. The integration does not follow it, so the key is never sent elsewhere; enter the address the browser ends on.

500 or another server error

The connection fails with WOOC-EXTN-1004.

429 or 503

iPaaS.com waits and tries again (WOOC-EXTN-1005).

A wrong key fails here, at connection time, not on a later record. Saving the subscription does not run this check. A failed connection shows on the transfer only as Unable to connect to subscription with id N. The integration writes the message with its code (WOOC-VALD-1001 to WOOC-VALD-1004, WOOC-AUTH-1001, WOOC-AUTZ-1001, WOOC-NFND-1001, WOOC-BIZL-1014, or WOOC-EXTN-1001 to WOOC-EXTN-1005) to the subscription's log page in iPaaS.com (open Subscriptions > your WooCommerce subscription, then its logs) at the same time. If no code appears there, check the Store URL setting.

Initialization Support

Currently, initialization is not supported for WooCommerce in iPaaS.com. All data synchronization and mappings must be configured manually during the integration process. Records arrive as they change, and the polls bring in only recent ones: the first order poll looks back Order Poll Initial Days and the first customer poll looks back Customer Poll Initial Days. To move a large existing data set, see bulk sync using Postman.

Throttling

Throttling keeps iPaaS.com from sending the store more calls than it can handle during heavy transfers. Every iPaaS.com subscription has the platform-standard settings API Throttle Limit, API Throttle Seconds, Concurrent Connections and Concurrent Batch Executions. They control how the iPaaS.com scheduler dispatches work.

While the throttling fields are required, the values are pre-populated by the integration settings. For more details, refer to Subscription Configuration – Edit.

Store rate limits

  • The WooCommerce REST API has no documented rate limit. Your host, firewall or security plugin may set one.

  • When the store answers 429 or 503, the integration raises WOOC-EXTN-1005. iPaaS.com waits for the store's Retry-After time (else 60 seconds) and tries again.

  • If WOOC-EXTN-1005 happens often, lower Concurrent Batch Executions by 1 (never below 1) and watch for a day before lowering it again, or ask your host to raise the limit for /wp-json/wc/v3/.

Before each transfer FROM iPaaS.com, the integration tells iPaaS.com how many calls it expects to make:

Transfer

Calls claimed

Product FROM iPaaS.com

2, plus 2 per category and tag, plus (when it has variants) 1, plus 1 per 100 variants

Product Variant FROM iPaaS.com

4

Product Inventory, Product Variant Inventory FROM iPaaS.com

1

Customer FROM iPaaS.com

3

Anything else

1

Persistent Data

The polls store their progress on the subscription as Persistent Data.

Key

Written by

Purpose

Last Date of Order Poll

order/poll

The newest order change the poll read, in UTC. The next poll asks for orders changed since then (less one second, so nothing on the boundary is missed).

Last Customer Id Polled

customer/poll

The highest customer id the poll has seen. The next poll sends customers with a higher id.

Linked Store

Every connection

The store this subscription's links belong to, recorded at its first successful connection. A Store URL naming another store is refused (WOOC-BIZL-1014); the same store at a new address, carrying this subscription's webhooks, updates it. It shows on the Subscription Settings page, where it can be deleted. Delete it only when this same store moved to a new address and is refused because no webhook scope was on: the next connection records the new address. Never delete it to connect a different store: this subscription's links would update unrelated records there.

Customer Poll Resume Below Id

customer/poll

Written only when a run stopped at its page limit before reaching the last customer already sent. The next run first sends the customers below this id, down to where the earlier run should have stopped, then clears it.

Each value is written once, at the end of a poll that found something newer. If you delete Last Date of Order Poll, the next order poll starts again from Order Poll Initial Days. If you delete Last Customer Id Polled (and Customer Poll Resume Below Id is empty), the next customer poll starts again like a first poll: newest customers first, limited to customers who registered in the last Customer Poll Initial Days.

Values Stored in WooCommerce

After writing a product's or variation's images, the integration stores a hidden meta entry named _ipaas_sync_{subscription id} (for example _ipaas_sync_12345) on that WooCommerce record. It holds a short fingerprint of the image list, so an unchanged list is not sent (and downloaded by WooCommerce) again. Each subscription keeps its own entry. If it is removed, the next update sends the images again.

Values Stored in iPaaS.com

The customer collections use a customer custom field named WooCommerce Sync Baseline. The collection that sends customers TO iPaaS.com fills it with a short fingerprint of the WooCommerce values iPaaS.com last received (no personal data); the collection that sends customers FROM iPaaS.com reads it back. When a customer is updated FROM iPaaS.com, a field changed in WooCommerce that iPaaS.com has not changed since is kept as WooCommerce has it (and is named in a warning log); a field iPaaS.com changed is written, even when WooCommerce changed it too. Leave both mappings in place: without them every mapped field is written. The fingerprint records which subscription wrote it; when another WooCommerce subscription in the same company wrote it last, every mapped field is written (see WooCommerce Integration Known Limitations).

Scopes Registered by the Integration

Scope name

Mapping Collection Type

Action

How it is triggered

order.created

Transaction

CREATED

WooCommerce webhook: a new order

order.updated

Transaction

UPDATED

WooCommerce webhook: an order changed (status, payment, refund, edits)

order/poll

Transaction

POLL

Polling: orders changed since the last poll

customer.created

Customer

CREATED

WooCommerce webhook: a new customer

customer.updated

Customer

UPDATED

WooCommerce webhook: a customer changed

customer/poll

Customer

POLL

Polling: customers created since the last poll

What turning each scope on does:

Scope

When turned on

When turned off

order.created

The integration registers an order.created webhook in WooCommerce. New orders come TO iPaaS.com when WooCommerce sends the order's order.created webhook.

The integration removes that webhook.

order.updated

The integration registers an order.updated webhook. Status changes, payments, refunds and edits come TO iPaaS.com when WooCommerce sends the order's order.updated webhook. Refunds arrive only through this webhook or order/poll.

The integration removes that webhook.

order/poll

Nothing is registered in WooCommerce. Changed orders come TO iPaaS.com each time the scheduled poll runs.

The poll no longer brings orders in.

customer.created

The integration registers a customer.created webhook. New customers come TO iPaaS.com when WooCommerce sends the customer.created webhook.

The integration removes that webhook.

customer.updated

The integration registers a customer.updated webhook. Customer changes come TO iPaaS.com when WooCommerce sends the customer.updated webhook. This is the only way a change to an existing customer reaches iPaaS.com.

The integration removes that webhook.

customer/poll

Nothing is registered in WooCommerce. New customers come TO iPaaS.com each time the scheduled poll runs.

The poll no longer brings customers in.

A poll scope runs only when a scheduled poll event exists for it. See the Installation Instructions.

FROM iPaaS.com flows (products, variants, stock and customers) do not use a WooCommerce scope. They run on iPaaS.com's own created and updated events.

WooCommerce Webhooks

When a webhook scope is turned on, the integration registers one webhook in WooCommerce for that topic (POST /wp-json/wc/v3/webhooks):

Item

Value

Name

iPaaS.com ({environment}, {subscription id}) {topic}, for example iPaaS.com (Production, 12345) order.created

Status

Active

Topic

The scope name: order.created, order.updated, customer.created or customer.updated

Delivery URL

{subscription webhook URL}/v2/dynamic/woocommerce?AuthToken={subscription webhook key}&subscription={subscription id}

  • Why the key is in the address. WooCommerce webhooks take only a delivery address. WooCommerce signs each delivery with its own secret, which iPaaS.com cannot check, so iPaaS.com checks the subscription's webhook key in the address instead. Store administrators can see the address under WooCommerce > Settings > Advanced > Webhooks. Do not share it or change it.

  • Which webhooks are this subscription's. A webhook belongs to the subscription when its delivery address goes to the iPaaS.com receiver, carries this subscription's id in its subscription value (or, for an address without one, this subscription's own key), and its topic matches. The name is only a label. Other webhooks in the store are never touched.

  • Already there. If the subscription's webhook for that topic exists, it is turned back on (if WooCommerce turned it off) and its name is updated. Duplicates of it are removed, so no event is delivered twice.

  • Turned off. Turning a scope off deletes the subscription's webhook for that topic.

  • Delivery timing. WooCommerce queues each delivery, so an event can take a few minutes to reach iPaaS.com.

  • Failed deliveries. WooCommerce turns a webhook off after more than five failed deliveries in a row. With a poll event set up, the integration turns this subscription's disabled webhooks back on at the start of its next poll (order/poll or customer/poll). The order poll then sends the orders the webhook missed; the customer poll finds new customers only, so a customer change made while the webhook was off arrives with that customer's next change (or bring it in now with a Manual Sync TO iPaaS.com of the customer's WooCommerce id). To stop a webhook, turn its scope off in iPaaS.com rather than disabling it in WooCommerce.

  • Webhook key changed. If the subscription's webhook key is regenerated, the next poll (or turning a scope on) moves this subscription's webhooks to the new key; they are recognised by the subscription id in their delivery address. Deliveries made before then fail: the order poll catches up orders, and a customer change made in that time arrives with that customer's next change (or bring it in now with a Manual Sync TO iPaaS.com of the customer's WooCommerce id).

Mapping Collection Types

Table

iPaaS.com type

Direction

WooCommerce Product

Product

FROM iPaaS.com

WooCommerce Product Variation

Product Variant (also a child of Product)

FROM iPaaS.com

WooCommerce Product Stock

Product Inventory (also a child of Product)

FROM iPaaS.com

WooCommerce Variation Stock

Product Variant Inventory (also a child of Product Variant)

FROM iPaaS.com

WooCommerce Order

Transaction (orders and refunds)

TO iPaaS.com

WooCommerce Order Line

Transaction Line (child of Order)

TO iPaaS.com

WooCommerce Order Address

Transaction Address (child of Order)

TO iPaaS.com

WooCommerce Order Payment

Transaction Payment (child of Order)

TO iPaaS.com

WooCommerce Order Tax

Transaction Tax (child of Order)

TO iPaaS.com

WooCommerce Order Coupon

Transaction Discount (child of Order)

TO iPaaS.com

WooCommerce Customer

Customer

TO iPaaS.com and FROM iPaaS.com

WooCommerce Customer Address

Customer Address (child of Customer)

TO iPaaS.com and FROM iPaaS.com

Table

Add

Update

Delete

Initialization

Polling

Webhook

Product, Product Variation

Yes

Yes

No

No

No

No

Product Stock, Variation Stock

Yes (stock-only)

Yes (stock-only)

No

No

No

No

Order

Yes

Yes

No

No

Yes (order/poll)

Yes (order.created, order.updated)

Customer, TO iPaaS.com

Yes

Yes

No

No

Yes (customer/poll)

Yes (customer.created, customer.updated)

Customer, FROM iPaaS.com

Yes

Yes

No

No

No

No

Custom fields

WooCommerce products, variations, orders, refunds and customers carry extra values called meta data. The integration treats each public meta entry (one whose key does not start with _) as a custom field:

  • TO iPaaS.com: an order's or customer's public meta entries are available as custom fields. To carry one, create two custom fields in iPaaS.com: one for the WooCommerce subscription on its WooCommerce Order table (orders and refunds) or WooCommerce Customer table, named exactly as the meta key, and the iPaaS.com custom field on the transaction or customer that will hold the value. Then, in the TO iPaaS.com collection, map the iPaaS.com field from the WooCommerce one (Custom to Custom). An order's meta keys are shown in the Custom Fields panel of the order screen in WordPress (turn the panel on under Screen Options if it is hidden); for a customer's, ask the extension or developer that adds the value.

  • FROM iPaaS.com: custom fields mapped on a product, variation or customer are written as meta entries with the same key.

External ids

Record

External id format

Example

Product

The WooCommerce product id

812

Product Variation

{product id}|{variation id}

812|815

Product Stock

{product id}|{iPaaS.com location id}

812|42

Variation Stock

{product id}|{variation id}|{iPaaS.com location id}

812|815|42

Order

The WooCommerce order id

1307

Refund (Return transaction)

{order id}-R{refund id}

1307-R1311

Order Line

{order or refund id}|{line id}; a fee: {order or refund id}|fee-{id}

1307|55, 1307|fee-57

Order Address

{order or refund id}|billing or |shipping

1307|shipping

Order Payment

{order or refund id}|payment

1307-R1311|payment

Order Tax

{order or refund id}|tax-{tax line id}

1307|tax-60

Order Coupon

{order id}|coupon-{coupon line id}

1307|coupon-61

Customer

The WooCommerce customer id

96

Customer Address

{customer id}|billing or {customer id}|shipping

96|billing

The ids are the ones WooCommerce shows in its admin screens, for example in the address of an order's edit page.

Related Documents

Did this answer your question?