# WooCommerce

Manage a WooCommerce store: orders, order notes and refunds, products and their variations, customers and coupons.

## Connect WooCommerce

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `woocommerce` and choose **WooCommerce**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Store URL · Required**: The WordPress site’s address, such as https://shop.example.com (the REST API is at /wp-json/wc/v3 below it).
- **Consumer key · Required**: ck_….
- **Consumer secret · Required**: cs_….

In WordPress: WooCommerce → Settings → Advanced → REST API → Add key, with Read/Write permission. Paste the store’s address and the consumer key and secret it shows once. The store must be served over HTTPS.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **WooCommerce**. The trigger uses the same connection as the steps.

### On WooCommerce Event

Fires when the store sends the chosen event. Publishing the workflow creates a webhook in the store (with a signing secret kept encrypted); unpublishing deletes it. Every delivery's X-WC-Webhook-Signature is checked and an unsigned or wrongly signed one is refused. WooCommerce turns a webhook off after 5 failed deliveries in a row.

- **Event · Required**: What starts the workflow. Options: Coupon created to Product updated (16 options). Default: Order created.

A later step can use its data, such as `{{trigger.id}}`, `{{trigger.status}}`, `{{trigger.woocommerce}}`. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in WooCommerce

Add a **WooCommerce** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Order](https://docs.gorunner.io/apps/woocommerce#fields-f-order): Create · Delete · Get · Get Many · Update
- [Order Note](https://docs.gorunner.io/apps/woocommerce#fields-f-ordernote): Create · Delete · Get Many
- [Refund](https://docs.gorunner.io/apps/woocommerce#fields-f-refund): Create · Get · Get Many
- [Product](https://docs.gorunner.io/apps/woocommerce#fields-f-product): Create · Delete · Get · Get Many · Update
- [Product Variation](https://docs.gorunner.io/apps/woocommerce#fields-f-productvariation): Create · Get · Get Many · Update
- [Customer](https://docs.gorunner.io/apps/woocommerce#fields-f-customer): Create · Delete · Get · Get Many · Update
- [Coupon](https://docs.gorunner.io/apps/woocommerce#fields-f-coupon): Create · Delete · Get · Get Many · Update

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from WooCommerce can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When WooCommerce says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, WooCommerce is `pieceId: "woocommerce"` with `actionId: "woocommerce"`, set by `resource` and an `operation_…` field, such as `operation_coupon`. Its trigger is `woocommercetrigger` / `woocommercetrigger`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### WooCommerce › Order

### Create

- **Status · Optional**: The order's status. Options: Pending payment, Processing, On hold, Completed, Cancelled, Refunded, Failed, Trash.
- **Customer ID · Optional**: The customer (0 for a guest).
- **Currency · Optional**: Three-letter code, such as EUR. Empty uses the store's.
- **Payment Method · Optional**: The gateway's id, such as bacs, stripe.
- **Payment Method Title · Optional**: As shown to the customer.
- **Set Paid · Optional**: Mark it paid (sets the status to processing and reduces stock).
- **Transaction ID · Optional**: The payment's id at the gateway.
- **Customer Note · Optional**: A note the customer left.
- **Billing · Optional**: {"first_name", "last_name", "company", "address_1", "address_2", "city", "state", "postcode", "country", "email", "phone"}.
- **Shipping · Optional**: {"first_name", "last_name", "company", "address_1", "address_2", "city", "state", "postcode", "country"}.
- **Line Items · Optional**: What was bought, such as [{"product_id": 93, "quantity": 2}] (add "variation_id" for a variation).
- **Shipping Lines · Optional**: such as [{"method_id": "flat_rate", "method_title": "Flat rate", "total": "5.00"}].
- **Fee Lines · Optional**: such as [{"name": "Gift wrap", "total": "2.50"}].
- **Coupon Lines · Optional**: such as [{"code": "AUTUMN"}].
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].
- **Additional Fields · Optional**: More of WooCommerce's fields for the order, as JSON by their API names. The fields above win over the same names here.

### Delete

- **Order ID · Required**: The order's number.
- **Delete Permanently · Optional**: Delete for good. Off moves it to the trash, where it can be restored.

### Get

- **Order ID · Required**: The order's number.

### Get Many

- **Status · Optional**: Only orders in this status. Options: any, Pending payment, Processing, On hold, Completed, Cancelled, Refunded, Failed, Trash.
- **Customer ID · Optional**: Only this customer's orders.
- **Product ID · Optional**: Only orders with this product.
- **Created After · Optional**: Only orders created after this moment. A date or date-time (RFC 3339).
- **Created Before · Optional**: Only orders created before this moment. A date or date-time (RFC 3339).
- **Modified After · Optional**: Only orders changed after this moment. A date or date-time (RFC 3339).
- **Search · Optional**: Text to find in the orders.
- **Order By · Optional**: Sort the list by. Options: date, id, include, title, slug, modified.
- **Order · Optional**: The sort direction. Options: Descending, Ascending.
- **Return All · Optional**: Read every order, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many orders to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Status · Optional**: The order's status. Options: Pending payment, Processing, On hold, Completed, Cancelled, Refunded, Failed, Trash.
- **Customer ID · Optional**: The customer (0 for a guest).
- **Payment Method · Optional**: The gateway's id, such as bacs, stripe.
- **Payment Method Title · Optional**: As shown to the customer.
- **Set Paid · Optional**: Mark it paid (sets the status to processing and reduces stock).
- **Transaction ID · Optional**: The payment's id at the gateway.
- **Customer Note · Optional**: A note the customer left.
- **Billing · Optional**: {"first_name", "last_name", "company", "address_1", "address_2", "city", "state", "postcode", "country", "email", "phone"}.
- **Shipping · Optional**: {"first_name", "last_name", "company", "address_1", "address_2", "city", "state", "postcode", "country"}.
- **Line Items · Optional**: What was bought, such as [{"product_id": 93, "quantity": 2}] (add "variation_id" for a variation).
- **Shipping Lines · Optional**: such as [{"method_id": "flat_rate", "method_title": "Flat rate", "total": "5.00"}].
- **Fee Lines · Optional**: such as [{"name": "Gift wrap", "total": "2.50"}].
- **Coupon Lines · Optional**: such as [{"code": "AUTUMN"}].
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].
- **Additional Fields · Optional**: More of WooCommerce's fields for the order, as JSON by their API names. The fields above win over the same names here.
- **Order ID · Required**: The order's number.

### WooCommerce › Order Note

### Create

- **Order ID · Required**: The order the note is on.
- **Note · Required**: The note's text.
- **Send to Customer · Optional**: Email it to the customer. Off keeps it private to the shop.

### Delete

- **Order ID · Required**: The order the note is on.
- **Note ID · Required**: The note.

### Get Many

- **Order ID · Required**: The order the note is on.
- **Return All · Optional**: Read every order note, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many order notes to return (1–1000). Default: 50. Shows when **Return All** is off.

### WooCommerce › Refund

### Create

- **Order ID · Required**: The order to refund.
- **Amount · Optional**: How much to refund. Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Reason · Optional**: Kept on the refund.
- **Refund Through the Gateway · Optional**: Send the money back through the payment gateway (when it supports refunds). Off only records the refund in the store.
- **Line Items · Optional**: The lines refunded, such as [{"id": 11, "quantity": 1, "refund_total": "19.95"}].

### Get

- **Order ID · Required**: The order to refund.
- **Refund ID · Required**: The refund.

### Get Many

- **Order ID · Required**: The order to refund.
- **Return All · Optional**: Read every refund, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many refunds to return (1–1000). Default: 50. Shows when **Return All** is off.

### WooCommerce › Product

### Create

- **Name · Optional**
- **Type · Optional**: The product type. Options: simple, grouped, external, variable.
- **Status · Optional**: Draft, pending review, private or published. Options: draft, pending, private, publish.
- **SKU · Optional**
- **Regular Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Sale Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Description · Optional**: HTML allowed.
- **Short Description · Optional**
- **Categories · Optional**: such as [{"id": 9}].
- **Images · Optional**: such as [{"src": "https://…/shirt.jpg"}] (the first is the main image).
- **Manage Stock · Optional**: Track the stock quantity.
- **Stock Quantity · Optional**: With Manage Stock on.
- **Stock Status · Optional**: Options: In stock, Out of stock, On backorder.
- **Weight · Optional**: In the store's weight unit.
- **Dimensions · Optional**: {"length", "width", "height"} as text.
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].
- **Additional Fields · Optional**: More of WooCommerce's fields for the product, as JSON by their API names. The fields above win over the same names here.

### Delete

- **Product ID · Required**: The product.
- **Delete Permanently · Optional**: Delete for good. Off moves it to the trash, where it can be restored.

### Get

- **Product ID · Required**: The product.

### Get Many

- **Search · Optional**: Text to find in products.
- **SKU · Optional**: Only the product with this SKU.
- **Status · Optional**: Options: any, draft, pending, private, publish.
- **Category ID · Optional**: Only products in this category.
- **Type · Optional**: Options: simple, grouped, external, variable.
- **Stock Status · Optional**: Options: instock, outofstock, onbackorder.
- **On Sale · Optional**: Only products on sale.
- **Order By · Optional**: Sort the list by. Options: date, id, include, title, slug, modified.
- **Order · Optional**: The sort direction. Options: Descending, Ascending.
- **Return All · Optional**: Read every product, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many products to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Name · Optional**
- **Type · Optional**: The product type. Options: simple, grouped, external, variable.
- **Status · Optional**: Draft, pending review, private or published. Options: draft, pending, private, publish.
- **SKU · Optional**
- **Regular Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Sale Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Description · Optional**: HTML allowed.
- **Short Description · Optional**
- **Categories · Optional**: such as [{"id": 9}].
- **Images · Optional**: such as [{"src": "https://…/shirt.jpg"}] (the first is the main image).
- **Manage Stock · Optional**: Track the stock quantity.
- **Stock Quantity · Optional**: With Manage Stock on.
- **Stock Status · Optional**: Options: In stock, Out of stock, On backorder.
- **Weight · Optional**: In the store's weight unit.
- **Dimensions · Optional**: {"length", "width", "height"} as text.
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].
- **Additional Fields · Optional**: More of WooCommerce's fields for the product, as JSON by their API names. The fields above win over the same names here.
- **Product ID · Required**: The product.

### WooCommerce › Product Variation

### Create

- **Product ID · Required**: The variable product.
- **Attributes · Optional**: such as [{"id": 1, "option": "Large"}].
- **SKU · Optional**
- **Regular Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Sale Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Manage Stock · Optional**
- **Stock Quantity · Optional**
- **Stock Status · Optional**: Options: instock, outofstock, onbackorder.
- **Additional Fields · Optional**: More of WooCommerce's fields for the variation, as JSON by their API names. The fields above win over the same names here.

### Get

- **Product ID · Required**: The variable product.
- **Variation ID · Required**: The variation.

### Get Many

- **Product ID · Required**: The variable product.
- **Return All · Optional**: Read every variation, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many variations to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Product ID · Required**: The variable product.
- **Attributes · Optional**: such as [{"id": 1, "option": "Large"}].
- **SKU · Optional**
- **Regular Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Sale Price · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Manage Stock · Optional**
- **Stock Quantity · Optional**
- **Stock Status · Optional**: Options: instock, outofstock, onbackorder.
- **Additional Fields · Optional**: More of WooCommerce's fields for the variation, as JSON by their API names. The fields above win over the same names here.
- **Variation ID · Required**: The variation.

### WooCommerce › Customer

### Create

- **Email · Optional**
- **First Name · Optional**
- **Last Name · Optional**
- **Username · Optional**: Empty lets WooCommerce make one from the email.
- **Billing · Optional**: {"first_name", "last_name", "company", "address_1", "city", "postcode", "country", "email", "phone"}.
- **Shipping · Optional**: {"first_name", "last_name", "company", "address_1", "city", "postcode", "country"}.
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].

### Delete and Get

- **Customer ID · Required**: The customer.

### Get Many

- **Email · Optional**: Only the customer with this email.
- **Search · Optional**: Text to find in customers.
- **Role · Optional**: Only customers with this WordPress role. Options: all, administrator, editor, author, contributor, subscriber, customer, shop_manager.
- **Order By · Optional**: Options: id, include, name, registered_date.
- **Order · Optional**: The sort direction. Options: Descending, Ascending.
- **Return All · Optional**: Read every customer, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many customers to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Email · Optional**
- **First Name · Optional**
- **Last Name · Optional**
- **Billing · Optional**: {"first_name", "last_name", "company", "address_1", "city", "postcode", "country", "email", "phone"}.
- **Shipping · Optional**: {"first_name", "last_name", "company", "address_1", "city", "postcode", "country"}.
- **Meta Data · Optional**: Custom fields, such as [{"key": "gift_note", "value": "Happy birthday"}].
- **Customer ID · Required**: The customer.

### WooCommerce › Coupon

### Create

- **Code · Optional**: What the customer types.
- **Discount Type · Optional**: Options: Percentage, Fixed cart discount, Fixed product discount.
- **Amount · Optional**: The discount: a percentage or an amount, by Discount Type. Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Individual Use Only · Optional**: Cannot be combined with other coupons.
- **Free Shipping · Optional**
- **Exclude Sale Items · Optional**
- **Minimum Spend · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Maximum Spend · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Usage Limit · Optional**: How many times it can be used in all.
- **Usage Limit per Customer · Optional**
- **Expires · Optional**: The day it stops working, such as 2026-12-31 (store time).
- **Allowed Emails · Optional**: Only these customers' emails, separated by commas.
- **Description · Optional**
- **Additional Fields · Optional**: More of WooCommerce's fields for the coupon, as JSON by their API names. The fields above win over the same names here.

### Delete

- **Coupon ID · Required**: The coupon.
- **Delete Permanently · Optional**: Delete for good. Off moves it to the trash, where it can be restored.

### Get

- **Coupon ID · Required**: The coupon.

### Get Many

- **Code · Optional**: Only the coupon with this code.
- **Search · Optional**: Text to find in coupons.
- **Return All · Optional**: Read every coupon, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many coupons to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Code · Optional**: What the customer types.
- **Discount Type · Optional**: Options: Percentage, Fixed cart discount, Fixed product discount.
- **Amount · Optional**: The discount: a percentage or an amount, by Discount Type. Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Individual Use Only · Optional**: Cannot be combined with other coupons.
- **Free Shipping · Optional**
- **Exclude Sale Items · Optional**
- **Minimum Spend · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Maximum Spend · Optional**: Text with a dot for decimals, exactly as the store shows it, such as 21.99.
- **Usage Limit · Optional**: How many times it can be used in all.
- **Usage Limit per Customer · Optional**
- **Expires · Optional**: The day it stops working, such as 2026-12-31 (store time).
- **Allowed Emails · Optional**: Only these customers' emails, separated by commas.
- **Description · Optional**
- **Additional Fields · Optional**: More of WooCommerce's fields for the coupon, as JSON by their API names. The fields above win over the same names here.
- **Coupon ID · Required**: The coupon.

Source: https://docs.gorunner.io/apps/woocommerce