# WooCommerce

WooCommerce integration with Ritevo: REST API keys, connecting the store, mapping statuses, payments and plugin fields (tax id, parcel locker), orders.

The WooCommerce integration brings orders from your WordPress store into Ritevo. You connect it with REST API keys generated in the WooCommerce panel. Because WooCommerce stores differ in their plugins, you set yourself how statuses, payment methods and plugin-added fields (tax id, pickup point) are read in Ritevo.

> **Required integration:** You need a working WooCommerce store and access to its admin panel to generate the API keys.

The same WooCommerce store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted.

Uniqueness: the integration is unique within the company by `externalId` and the type `WOOCOMMERCE`; `externalId` is the store url without a trailing `/` (a url ending in `/` is saved without it). Creating it again with the same url refreshes the existing integration instead of adding a new one: it replaces the credentials, sets `authError=false` and `active=true` and returns that integration. You can also send new credentials with `PATCH /integrations/shops/woocommerce/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`.

## How to generate the API key

You create the keys in your store's WordPress panel. Copy both right away - you will paste them into Ritevo when adding the integration.

1. Sign in to the WordPress panel and in the left menu choose **WooCommerce**, then **Settings**.
2. Open the **Advanced** tab, then **REST API**. Click **Add key**.
3. In the **Description** field enter any name, for example "Ritevo". In the **User** field pick the store's administrator account.
4. In the **Permissions** field choose **Read/Write** - the highest available - and click **Generate API key**.
5. Copy the **Consumer key** and the **Consumer secret**.

> **Good to know:** WooCommerce shows the consumer secret only once, right after generating. If you close the page without copying it, generate a new key. A key with **Read** permission only will not work - Ritevo rejects it when adding.

## Connecting the account

Start in Ritevo:

1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner.
2. In the **Online stores** section pick the **WooCommerce** tile.
3. In the **Account name** field enter your own name for the integration, for example the store's name.
4. In the **Store address** field enter the store's full address with `https://`, without a trailing slash and without `/wp-admin` - for example `https://mystore.com`.
5. In the **Consumer Key** and **Consumer Secret** fields paste the keys from the WooCommerce panel.
6. Click **Add integration**. Ritevo connects to the store right away and checks the details: if they are valid, the integration is added and its settings open. If not - you will see the error returned by the store and nothing is saved.

![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp)

![The Add integration screen with the WooCommerce tile framed in the Online stores section](https://ritevo.com/docs/integrations/woocommerce/en-catalogue.webp)

![The WooCommerce add-integration screen with the Account name, Store address, Consumer Key and Consumer Secret fields](https://ritevo.com/docs/integrations/woocommerce/en-add.webp)

## Integration settings

After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find:

- **Account name** - your own name for this integration, for example the store's name. You can change it at any time.
- **Store address** - the address given when adding. It cannot be changed here; a new address or new keys go through **Update credentials**.
- **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders).
- **Order status mapping**, **Payment method mapping** and **Advanced mapping** - described below.

![WooCommerce integration details: the account name, store address, the Fetch orders switch and the Order status mapping card](https://ritevo.com/docs/integrations/woocommerce/en-details.webp)

> **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error.

## Mapping statuses and payments

Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on.

> **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point.

### Order status mapping

Ritevo reads the status list from your store, including statuses added by plugins, so you see them under the same names as in the WooCommerce panel. **Up front** the standard WooCommerce statuses are assigned. **You assign yourself** the statuses added by plugins. The starting assignment:

- **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - Processing, Completed, Refunded. A refunded order was a real sale, so it stays confirmed - you settle the refund separately.
- **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - Cancelled.
- **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - Pending payment, Failed.
- **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - On hold.

One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do.

### Payment method mapping

Ritevo reads the method list from the payment gateways enabled in your store. **Up front** the methods built into WooCommerce are assigned. **You assign yourself** plugin gateways (Stripe, PayPal, Klarna and others), because every store has different ones. The starting assignment:

- **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - Direct bank transfer, Check payments.
- **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - Cash on delivery.

A payment made with a method you have not assigned anywhere arrives as **Other**.

![The Payment method mapping card of the WooCommerce integration with Direct bank transfer, Check payments and Cash on delivery assigned](https://ritevo.com/docs/integrations/woocommerce/en-payments.webp)

### Advanced mapping - plugin fields

WooCommerce has no standard fields for a tax id, an invoice request or a pickup point - plugins add them, each under its own field name. In this card you point to the order field Ritevo should read each of these from. **Up front** the field names of popular plugins are filled in. **You add yourself** the field names of other plugins and remove the ones you do not need.

- **Tax id / VAT number** (API: "Tax id / VAT number" = `TAX_ID`; value in `fieldMappings[].field`) - the field with the buyer's tax id. When it has a value, the order gets the company details and the number for the invoice.
- **Invoice request** (API: "Invoice request" = `INVOICE_REQUESTED`; value in `fieldMappings[].field`) - the field Ritevo reads to tell whether the buyer wants an invoice. Only the value in the field matters: if it is "0", "no", "false" or "off", there is no request; any other value (for example "1", "yes", "true") is a request. When the field is empty, an invoice is requested whenever the buyer gave a tax id.
- **Pickup point id** (API: "Pickup point id" = `PICKUP_POINT_ID`; value in `fieldMappings[].field`) - the field with the locker or point code (for example `WAW123`).
- **Pickup point name** and **Pickup point description** (API: "Pickup point name" = `PICKUP_POINT_NAME`, "Pickup point description" = `PICKUP_POINT_DESCRIPTION`; value in `fieldMappings[].field`) - the fields with the point's name and address, if the plugin stores them.
- **Pickup point country** (API: "Pickup point country" = `PICKUP_POINT_COUNTRY`; value in `fieldMappings[].field`) - usually stays empty; Ritevo then takes the country from the delivery address.

You will find the field name in the plugin's settings or in the details of a test order. Enter it exactly - letter case and the leading underscore matter. One field can hold several names (for example after switching plugins): Ritevo uses the first one that has a value in the order.

![The Advanced mapping card of the WooCommerce integration with the Tax id / VAT number, Invoice request and pickup point fields, plus the Update credentials and Update integration buttons](https://ritevo.com/docs/integrations/woocommerce/en-advanced.webp)

> **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively.

You save the mappings with `PATCH /integrations/shops/woocommerce/{integrationId}` together with `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` (`{ field, keys }`) with every value listed above. Each list must carry every value of its enum - send an unassigned value with an empty list. `externalIds` are WooCommerce status slugs and payment gateway ids. The current shape is in Swagger.

## What this integration gives you

- **Orders** - new and changed WooCommerce orders land in the orders table, with the buyer's details, invoice details, delivery (including the plugin's pickup point) and line items with product images.

## Orders from WooCommerce

Ritevo fetches the whole WooCommerce order: the buyer, billing and shipping address, shipping method, payment, line items with gross prices and product images. An order changed in the store (for example a new status) is fetched again.

- **Statuses and payments** - translated according to your mapping, described above.
- **Invoice** - the company details and tax id are read from the fields set in **Advanced mapping**; with neither a company name nor a tax id the order has no invoice details. The invoice request follows the **Invoice request** field and gives the **Customer asks for an invoice** flag.
- **Pickup point** - the point's code and name are read from the fields set in **Advanced mapping**; without them the order has only the delivery address.
- **Buyer's note** - the order note typed at checkout goes into the order as the buyer's message.
- **Additional services** - supported. Fees the shop added to the order, for example for gift wrapping or carry-in, show up as separate line items for the whole order. A discount added as a fee shows up with a negative amount. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services).
- **Guest checkout** - a guest order is fetched normally; the buyer then has no store customer id.

> **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages).

## Reconnection required

This state appears when the store stopped accepting the credentials - the key was deleted in the store's panel, lost its permissions, or the store address changed. Until you provide new details, Ritevo neither fetches nor sends any data from that store.

1. Generate new keys in the store's panel - the same way as when connecting for the first time.
2. On the integration page in Ritevo click **Update credentials**, enter the store address and the new keys and confirm. Ritevo checks them with the store just like when adding - wrong details return an error, valid ones refresh the connection. The mappings, fetching settings and history stay unchanged.

> **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately.

In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page.

## Deleting the integration

**Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on.

## What the integration does not do

- It does not manage listings: it does not list, change prices or stock in WooCommerce.
- It does not fetch messages - WooCommerce has no buyer inbox. Customers write by email, so add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for the store's mailbox.
- It sends nothing back to WooCommerce: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in WooCommerce stays unchanged.

## The integration through the API

This integration's endpoints are under `/integrations/shops/woocommerce`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs.


---

All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.