Skip to content
Docs
E-commerce

WooCommerce

Let hires look up orders, customers and products in your WooCommerce store, leave notes, move orders along, and ask before any refund.

Explore 8 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With WooCommerce connected, a hire can:

  • list orders by status, customer, words (an order number, a name, a product) and dates,
  • read an order: its lines, totals, payment, shipping method, refunds so far, the customer's checkout note and the order's notes,
  • find registered customers and see their latest orders,
  • list products with their price and stock,
  • leave a private note on an order, and move an order to on hold, processing or completed,
  • refund an order, but only once a person approves that exact refund.

Hires never cancel orders, edit them or charge anyone. They don't write notes to the customer either: notes are always private to your team.

1. Connect it in one click

Your store must be reachable at an https:// address, and you'll need to sign in to it as a shop manager or administrator.

  1. Open Integrations → Tools → Add a tool, search for WooCommerce and choose it.
  2. Store address: your store's address, like https://shop.example.com.
  3. Click Approve in WooCommerce. Your store opens and asks whether to give Roster access; click Approve.

WooCommerce makes a key for Roster itself and sends it straight to Roster, and you come back to Roster connected. There's nothing to copy or paste. The key shows up under WooCommerce → Settings → Advanced → REST API as Roster, where you can revoke it at any time.

Or paste a key yourself

If your store can't open the approve page (some hosts block it), click Paste a key instead:

  1. Roster links to your store's Add key page (WooCommerce → Settings → Advanced → REST API → Add key).
  2. Describe it as Roster, choose the user it acts as (a shop manager or administrator), and set Permissions to Read/Write, or Read if hires should only look things up.
  3. Click Generate API key, copy the Consumer key (ck_…) and Consumer secret (cs_…) into Roster, and click Connect. WooCommerce shows the secret only once.

Either way, Roster checks the key with your store straight away and shows which store it's for.

2. Give hires access

On the hire's Tools tab, click Give access on WooCommerce:

  • Read only: it can look up orders, customers and products, and nothing else.
  • Read and write: it can also leave private notes, change an order's status between on hold, processing and completed, and ask to refund.
  • Customer details: Names only (the default) shows customers' names and the city and country an order goes to, and takes emails and phone numbers out of what customers wrote. Names, emails and phone numbers shows those too. Street addresses are never shown.

When a hire marks an order processing or completed, WooCommerce may email the customer, just as it does when someone on your team makes that change. Cancelled, refunded and failed orders are left for a person to change.

Refunds always wait for approval

A refund is money leaving your business, so it always waits for a person's approval, and nobody can turn that off. The hire asks in the thread with the order, the amount and the reason; when the approver says yes, Roster makes exactly that refund, once.

The refund goes back through your store's payment gateway, as when you refund in WooCommerce with the gateway's refund button. If the money was already returned another way (a bank transfer, cash), the hire can ask to only record the refund in WooCommerce instead. If your gateway can't refund automatically, WooCommerce says so and nothing is refunded.

Watching orders

A hire's responsibility can watch WooCommerce: it's woken when an order is placed or changes, with the order number, total, status and customer's name.

If something goes wrong

  • "Consumer key is missing" or "Sorry, you cannot list resources" while the key is right: some hosts drop the sign-in header on its way to WordPress. Ask your host to pass the Authorization header through to PHP.
  • The approve page shows "page not found", or Roster says the key didn't arrive: your store or its host is blocking the approve page or Roster's request. Use Paste a key instead.
  • Changes refused with 401: the key has Read permission only. Make a Read/Write key.
  • Nothing found: check the store address is the one your shop is at, with https://.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect WooCommerce and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

User name and password or key pair

In WordPress: WooCommerce → Settings → Advanced → REST API → Add key (ck_… and cs_…).

When making a key, use these permissions from the connection guide:

  • Read/Write (or Read for look-ups only)

Connection fields

WooCommerce connection fields
FieldWhat to provide
Consumer key
consumerKey
Optional		In WordPress: WooCommerce → Settings → Advanced → REST API → Add key (ck_… and cs_…).
Consumer secret
consumerSecret
Optional · sealed secret		Use the value for your account or connection.
Store address
url
Required		Your store's own address, starting https://.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

WooCommerce per-hire limits
FieldWhat to provide
Customer details
customers
Optional		What it sees of your customers. Street addresses are never shown.

Choices: Names only (names); Names, emails and phone numbers (full).

Starts with: names.

Actions

8 actions: 5 only read and 3 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

8 of 8 actions. Open an action for its arguments and full input schema.

list_ordersRead only

Orders, newest first: by status, customer (their id or email), words (order number, name, email or product), and dates placed.

Approval: Uses your workspace and hire approval settings.

Arguments for list_orders
ArgumentTypeDetails
statusOptional"any" | "pending" | "processing" | "on-hold" | "completed" | "cancelled" | "refunded" | "failed"See input schema below.Default: "any"
customerOptionalstringa registered customer's id or email
searchOptionalstringSee input schema below.
fromOptionalstringplaced on or after, yyyy-mm-dd
toOptionalstringplaced on or before, yyyy-mm-dd
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "pending",
        "processing",
        "on-hold",
        "completed",
        "cancelled",
        "refunded",
        "failed"
      ]
    },
    "customer": {
      "description": "a registered customer's id or email",
      "type": "string"
    },
    "search": {
      "type": "string",
      "maxLength": 200
    },
    "from": {
      "description": "placed on or after, yyyy-mm-dd",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "to": {
      "description": "placed on or before, yyyy-mm-dd",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
get_orderRead only

One order in full: lines, totals, payment, shipping method, refunds so far, the customer's checkout note, and the order's notes.

Approval: Uses your workspace and hire approval settings.

Arguments for get_order
ArgumentTypeDetails
idRequiredintegerthe order's id (shown as id …; often its number too)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the order's id (shown as id …; often its number too)"
    }
  },
  "required": [
    "id"
  ]
}
find_customersRead only

Registered customers matching words in their name or email, newest first.

Approval: Uses your workspace and hire approval settings.

Arguments for find_customers
ArgumentTypeDetails
searchOptionalstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
get_customerRead only

One registered customer and their latest orders.

Approval: Uses your workspace and hire approval settings.

Arguments for get_customer
ArgumentTypeDetails
idRequiredintegerSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ]
}
list_productsRead only

Products with their price and stock: by words, SKU or stock status.

Approval: Uses your workspace and hire approval settings.

Arguments for list_products
ArgumentTypeDetails
searchOptionalstringSee input schema below.
skuOptionalstringSee input schema below.
stockOptional"any" | "instock" | "outofstock" | "onbackorder"See input schema below.Default: "any"
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200
    },
    "sku": {
      "type": "string",
      "maxLength": 100
    },
    "stock": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "instock",
        "outofstock",
        "onbackorder"
      ]
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
add_noteRead and write

Leave a private note on an order, for the team only. The customer never sees it and isn't emailed.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
idRequiredintegerthe order's id (shown as id …; often its number too)
noteRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the order's id (shown as id …; often its number too)"
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000
    }
  },
  "required": [
    "id",
    "note"
  ]
}
set_statusRead and write

Move an order to on hold, processing or completed. WooCommerce may email the customer as it does when your team makes the change. Cancelling, failing and refunding aren't done here.

Approval: Uses your workspace and hire approval settings.

Arguments for set_status
ArgumentTypeDetails
idRequiredintegerthe order's id (shown as id …; often its number too)
statusRequired"on-hold" | "processing" | "completed"See input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the order's id (shown as id …; often its number too)"
    },
    "status": {
      "type": "string",
      "enum": [
        "on-hold",
        "processing",
        "completed"
      ]
    }
  },
  "required": [
    "id",
    "status"
  ]
}
refund_orderRead and writeApproval required · locked

Refund an order, in full or in part, through the store's payment gateway (or record a refund already paid another way). Money moving always waits for a person's approval: Roster asks in the thread and makes exactly this refund, once, when they approve. Leave the amount out to refund whatever is left.

Approval: Always asks for approval. This requirement cannot be turned off.

Arguments for refund_order
ArgumentTypeDetails
idRequiredintegerthe order's id (shown as id …; often its number too)
amountOptionalnumberhow much, e.g. 120.50
currencyOptionalstringthe order's currency; needed with amount
reasonRequiredstringwhy, kept on the refund
record_onlyOptionalbooleantrue when the money was already returned outside the gateway: only records itDefault: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the order's id (shown as id …; often its number too)"
    },
    "amount": {
      "description": "how much, e.g. 120.50",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "description": "the order's currency; needed with amount",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "why, kept on the refund"
    },
    "record_only": {
      "default": false,
      "description": "true when the money was already returned outside the gateway: only records it",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "reason"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Shopify

Let hires look up orders, shipping and tracking, customers and products in your Shopify store, tag orders and add notes, and be woken when orders change. Refunds stay with your team.

Bird

SMS, WhatsApp and email messaging through Bird (MessageBird).

On this page

1. Connect it in one clickOr paste a key yourself2. Give hires accessRefunds always wait for approvalIf something goes wrongTools and permissions reference