# Ecomanager integration: send your orders to Ecomanager

**Category:** External platforms  ·  **Min plan:** Pro  ·  **Page:** `/dashboard/addons/ecomanager`

**Ecomanager** is an e-commerce platform for managing orders and deliveries, where each shop has its own address of the form `https://your-store.ecomanager.dz`. If your team confirms and ships orders from Ecomanager, this integration puts your DZBuild orders into your Ecomanager shop without retyping them, and brings the Ecomanager state of each order back onto the matching DZBuild order.

## What the integration does

* **Sends new orders.** Orders placed on your storefront and on your [landing pages](https://dzbuild.com/docs/selling/landing-pages.md) go to Ecomanager in the background while **Sync new orders** is on. They arrive in Ecomanager in the **En confirmation** state.
* **Lets you send the others by hand.** Any other order, for example one you create on the [Orders](https://dzbuild.com/docs/selling/orders.md) page or one placed before you connected, waits on the integration page until you send it.
* **Brings states back.** Once you register the webhooks, each state change in Ecomanager updates the status of the DZBuild order, and a tracking number given by Ecomanager is copied onto the order.
* **Skips orders already sent.** An order that already carries an Ecomanager reference is not sent again.

Status changes travel one way only. DZBuild does not send status changes to Ecomanager, so an order you confirm or cancel in DZBuild keeps its previous state in Ecomanager. Make those changes in Ecomanager and let them come back.

## What Ecomanager receives

Each order arrives in Ecomanager with:

* the buyer's name, phone number, wilaya, commune and address, plus the email and the note when the buyer gave them;
* every product line with its SKU, quantity and unit price;
* the shipping cost, the discount, and whether it is a home or a stop desk delivery.

The phone number is sent in the local format starting with 0, so a number written with `+213` is rewritten. The commune is sent under its French name, to match the commune list in Ecomanager.

Before sending, DZBuild looks for each product in your Ecomanager shop, first by SKU, then by name. A product it cannot find is created in Ecomanager with its name, SKU and price. If the product has no SKU in DZBuild, it receives the SKU it carries in Ecomanager; when DZBuild has to make one up, it starts with `DZBUILD-`. DZBuild sends one SKU per product, so two variants of the same product arrive under the same SKU.

## Order states that come back

Ecomanager states reach DZBuild in two ways: through the webhooks once you register them, and when you press the refresh button on a sent order. Each state replaces the status of the DZBuild order:

| Ecomanager state     | Your DZBuild order becomes |
| -------------------- | -------------------------- |
| En confirmation      | Pending                    |
| En préparation       | Confirmed                  |
| En dispatch          | Processing                 |
| En livraison         | Shipped                    |
| Livrée, Encaissée    | Delivered                  |
| En retour, Retournée | Returned                   |
| Annulée              | Cancelled                  |

Stock follows the new status by the same rule as when you change it yourself (see [Orders](https://dzbuild.com/docs/selling/orders.md)). A change that arrives by webhook also updates the order's row in [Google Sheets](https://dzbuild.com/docs/operations/google-sheets.md) when your store uses it, and sends you the same order status update alert as a change you make yourself (see [Notifications](https://dzbuild.com/docs/operations/notifications.md)).

With the webhooks registered, deleting an order in Ecomanager does not delete it in DZBuild: the order loses its Ecomanager reference and goes back to the list of orders waiting to be sent, unless it is cancelled.

## What it costs

The integration has no price of its own on DZBuild, and nothing is charged per order sent. The card lets you connect on the Pro, Unlimited and Enterprise plans. On the Free plan it shows a **PRO** badge and an **Upgrade to Pro** button that opens [`/dashboard/subscribe`](https://dzbuild.com/dashboard/subscribe). Your Ecomanager subscription is billed by Ecomanager.

## How to connect

1. In Ecomanager, log in to your account, open **Shop Configuration** and copy the **API Token**.
2. In DZBuild, open **Dashboard → Add-ons** at [`/dashboard/addons`](https://dzbuild.com/dashboard/addons), find the **Ecomanager** card in the **External platforms** section and click **Connect Ecomanager**.
3. In **Your Ecomanager store URL**, type only your shop's slug, without `https://` and without `.ecomanager.dz`. For `https://my-shop.ecomanager.dz`, type `my-shop`. The full address appears under the field as you type.
4. Paste the token into **API key**.
5. Click **Test and connect**. DZBuild checks the slug and the token against your Ecomanager shop and saves the connection only if the check passes. **Test connection only** runs the same check without saving anything.
6. When the page reloads with the **Connected** badge, press **Register Webhooks** so that Ecomanager states come back to DZBuild.

**Sync new orders** is on from the first connection, so your next storefront order goes to Ecomanager with no other step.

## Using the integration page

### Counters

Four tiles sit at the top: **Total orders**, **Orders sent**, **Waiting for sync** and **Last sync**. **Waiting for sync** counts every order without an Ecomanager reference, cancelled ones included, while the list below leaves cancelled orders out.

### Orders waiting to be sent

This list shows your 20 most recent orders that carry no Ecomanager reference, cancelled orders excepted, with the order number, the buyer, the amount and the status. Each row has its own send button. **Send all** sends the orders you ticked, or every order in the list when none is ticked, after you confirm. One press sends up to 20 orders; the page then reloads and older orders take their place.

If a group send fails, send the orders one by one with the button on each row. The message tells you what Ecomanager refused, for example a product it could not create.

### Sent orders

This list shows the 20 most recently updated sent orders, with the order number, the **Eco ref** (the Ecomanager reference), the buyer and the DZBuild status. The **Refresh status** button on a row reads the order's current state in Ecomanager, then updates the status and the tracking number of the DZBuild order.

### Sync settings

**Sync new orders** turns automatic sending on or off. Press **Save** after changing it. The **Order status updates** row below it is not a switch: it reads "Automatic updates via Webhooks", because states come back through the webhooks.

### Webhooks

**Register Webhooks** creates four webhooks in your Ecomanager account: one for status changes, one for shipping status changes, one for confirmation status changes and one for deleted orders. Their names in Ecomanager start with `DZBuild -`. Once they are registered, the card shows **Registered** and the button becomes **Re-register**.

### Connection details

This card lists your shop URL, the last six characters of the API token and the status **Active**. **Disconnect** asks for a confirmation, then stops sending orders and receiving states; orders already sent stay in Ecomanager. When you connect again, **Sync new orders** is back on and you need to press **Register Webhooks** again, because the webhooks from the earlier connection are no longer accepted.

## When something goes wrong

The page shows the reason in a message. The most common ones:

* The link must be in the form `https://slug.ecomanager.dz`: the store URL field holds more than the slug, for example the full address. Type only the slug, made of Latin letters, digits and hyphens.
* The API key is invalid or expired: copy the token again from **Shop Configuration** and reconnect.
* Too many requests: Ecomanager is limiting calls for a moment, so wait a little and try again.
* Ecomanager server error: Ecomanager did not answer correctly, so try again later.
* A product could not be created: the message names the product and gives the reason Ecomanager returned.

If Ecomanager reports that your account is suspended, for example after an expired subscription or unpaid bills, DZBuild disconnects the integration on its own. Once your Ecomanager account is active again, connect it again and register the webhooks. Orders that could not be sent stay in **Orders waiting to be sent**, ready to send.

## FAQ

**Do I have to send each order myself?** No. With **Sync new orders** on, orders from your storefront and your landing pages go to Ecomanager on their own. Use the waiting list for older orders and for orders created any other way.

**Can an order reach Ecomanager twice?** DZBuild stores the Ecomanager reference of every order it sends and skips that order on later sends, so pressing **Send all** again does not copy it.

**I changed an order's status in DZBuild. Why does Ecomanager still show the old state?** DZBuild does not send status changes to Ecomanager. Change the state in Ecomanager instead: with the webhooks registered, the new state comes back to DZBuild.

**An order's status changed in DZBuild without me touching it. Why?** The order changed state in Ecomanager and a webhook applied it. Ecomanager states replace the DZBuild status, as shown in the table above.

**Where do I find the API token?** In your Ecomanager account, on the **Shop Configuration** page, under **API Token**.

**Can I connect Ecomanager on the Free plan?** No. The card needs the Pro, Unlimited or Enterprise plan. The other external platforms are listed in the [Add-ons catalog](https://dzbuild.com/docs/addons/overview.md), and [Flash Manager](https://dzbuild.com/docs/addons/flash-manager.md) connects on every plan.