# WooCommerce

Source: https://gokarla.io/docs/guides/shops/woocommerce

# WooCommerce

:::info

The WooCommerce integration uses Karla's public API and WooCommerce's native
webhooks. You don't need a plugin — just point WooCommerce's webhook system at
Karla and you're done.

:::

## What you need

- A WooCommerce store (WordPress 5.0+ with WooCommerce 3.5+)
- Admin access to your WooCommerce dashboard
- A Karla API key (generate one under **Settings → API Keys** in your Karla portal)
- Your Karla **shop slug**

## Overview

Karla ingests orders and tracking updates through a set of HTTP endpoints.
WooCommerce can push data to those endpoints natively via webhooks, which means
integration is a matter of configuration — no code, no plugin.

You'll configure three webhooks:

1. **Order created** — when a customer completes checkout.
2. **Order updated** — when an order status changes (e.g. `processing` → `completed`).
3. **Order deleted** — when an order is cancelled or removed.

Karla receives each event, normalizes the payload, and begins tracking the
shipment as soon as a tracking number is attached.

## Step 1 — Generate your Karla API key

1. Sign in to the [Karla Portal](https://portal.gokarla.io).
2. Navigate to **Settings → API Keys**.
3. Click **Create API Key**, pick the `editor` role, and copy the generated key.
4. Note your **shop slug** — it appears at the top of every Karla portal page.

Keep the key and slug handy; you'll paste them into WooCommerce.

## Step 2 — Create the webhook endpoint URL

Karla's order webhook endpoint is:

```text
https://api.gokarla.io/v1/shops/{your-shop-slug}/orders/woocommerce
```

Replace `{your-shop-slug}` with your actual slug.

## Step 3 — Configure WooCommerce webhooks

1. In your WordPress admin, go to **WooCommerce → Settings → Advanced → Webhooks**.
2. Click **Add webhook**.
3. For each of the three events, create a webhook with these settings:

   | Field            | Value                                                                 |
   | ---------------- | --------------------------------------------------------------------- |
   | **Name**         | `Karla — Order created` (adjust per topic)                            |
   | **Status**       | `Active`                                                              |
   | **Topic**        | `Order created` / `Order updated` / `Order deleted`                   |
   | **Delivery URL** | `https://api.gokarla.io/v1/shops/{your-shop-slug}/orders/woocommerce` |
   | **Secret**       | Leave empty (Karla authenticates with the header below)               |
   | **API Version**  | `WP REST API Integration v3` (latest)                                 |

4. Click **Save webhook**.

## Step 4 — Add the Karla authorization header

WooCommerce doesn't expose a headers field in the webhook UI by default. Use the
[Webhook Tools](https://wordpress.org/plugins/wp-webhooks/) plugin or a small
snippet in your theme's `functions.php`:

```php
add_filter(
  'woocommerce_webhook_http_args',
  function ($http_args, $arg, $id) {
    $webhook = wc_get_webhook($id);
    if (str_contains($webhook->get_delivery_url(), 'api.gokarla.io')) {
      $http_args['headers']['Authorization'] = 'Basic ' . base64_encode(
        '{your-shop-slug}:{your-karla-api-key}'
      );
    }
    return $http_args;
  },
  10,
  3
);
```

Replace `{your-shop-slug}` and `{your-karla-api-key}` with your actual values.
This attaches HTTP Basic auth to every request Karla receives.

:::tip

For production setups we recommend storing credentials in
[wp-config.php constants](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/)
or a secrets manager, not directly in `functions.php`.

:::

## Step 5 — Verify

1. Place a test order in your WooCommerce store.
2. Open the **Karla Portal → Orders** view — your test order should appear
   within a few seconds.
3. Update the order status in WooCommerce (e.g. mark as completed) and verify
   Karla reflects the change.

If an order doesn't appear, check **WooCommerce → Settings → Advanced → Webhooks
→ Logs** for delivery errors (most commonly a 401 — double-check the
authorization header).

## Tracking numbers

When you add a tracking number to an order in WooCommerce (via a plugin such as
**Advanced Shipment Tracking** or the native meta field), include it in the
order's line-item or order meta and WooCommerce will pass it along on the next
`Order updated` webhook. Karla reads these standard meta keys:

- `_tracking_number`
- `_tracking_provider` (or `_tracking_carrier`)

For custom setups, you can also push tracking numbers directly to Karla using
the [shipments endpoint](/docs/platform/shipments).

## Next steps

- Set up [Notify integrations](/docs/guides/notify/disable-carrier-emails) so
  your customers receive branded shipment updates.
- Connect [carrier integrations](/docs/guides/carriers/overview) so
  Karla can track each shipment in real time.
- Customize your [tracking page](/docs/guides/tracking-page/overview) to match
  your store's branding.