> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-guides/receiving-orders-from-a-sales-channel.md).

# Receiving orders from a sales channel

Send orders from a shop or marketplace into OrderEazi through a sales channel, cancel them, and book their courier.

When a client buys on your online shop or a marketplace, the order needs to reach the people who fulfil it without anyone recapturing it. The OrderEazi API takes the order in through a sales channel. A sales channel is the setup in OrderEazi that says which workflow, sales rep, and warehouses an outside system's orders use.

OrderEazi creates a project (its record of an order, with the order's lines and documents) and adds the lines. It can also approve the order and create the Sales Order (the document that confirms an order to the client) straight away.

### Before you start

You'll need:

* **A sales channel:** The organisation sets one up for your shop under **Integrations** > **Sales Channels**, with its workflow and at least one warehouse. You use its name in the request path. See [Sales Channels](/central/order-management/integrations/sales-channels.md).
* **Permissions:** Your key needs **Write** on **For Project**. See [Authentication](/central/developers/authentication.md).
* **Matching product codes:** Each line's `Code` should be the product's SKU (stock keeping unit, the product code) in OrderEazi.

### How to send an order

Send a POST to `/api/order/{channel}`, where `{channel}` is the sales channel's name, URL-encoded. The smallest order is a list of lines:

```bash
curl -X POST https://yourcompany.ordereazi.com/api/order/WebShop \
  -H "X-OrderEazi-Key: YOUR_API_KEY" \
  -H "x-api-version: 2.0" \
  -H "Content-Type: application/json" \
  -d '{ "Lines": [ { "Code": "CHAIR-01", "Quantity": 2 } ] }'
```

A fuller order looks like this:

```json
{
  "CompanyName": "Clientco",
  "Name": "Thandi",
  "Surname": "Nkosi",
  "EmailAddress": "thandi@example.com",
  "ContactNumber": "0115550000",
  "OrderNumber": "WEB-10045",
  "OrderReference": "PO 7781",
  "DueDate": "2026-11-20T00:00:00",
  "DeliveryType": "COURIER",
  "Instructions": "Leave at reception",
  "ShippingAddress": {
    "StreetAddress": "12 Main Rd",
    "Suburb": "Rosebank",
    "City": "Johannesburg",
    "Province": "Gauteng",
    "Country": "ZA",
    "StreetCode": "2196"
  },
  "KeyValues": { "WebStoreId": "10045" },
  "Tags": ["web"],
  "Lines": [
    { "Code": "CHAIR-01", "Quantity": 2, "SellingPrice": 1450.00 },
    { "Code": "MUG-11", "Quantity": 6, "DiscountPercentage": 10 }
  ]
}
```

The response gives you the new project's number:

```json
{
  "Success": true,
  "Warnings": [],
  "Data": {
    "ProjectId": "6f1c2a9e-0b7d-4c4f-9a51-1f0b8f6a2d11",
    "ProjectNumber": "PRO001234",
    "SalesOrderNumber": "SO000567",
    "ShippingResponse": null,
    "CollectionShippingResponse": null,
    "Warnings": []
  }
}
```

Store the `ProjectNumber` against your order. You need it to cancel the order or book its courier later.

### How the order is set up

* **Client:** Send a `ClientId` to use a client that's in OrderEazi, or a `CompanyName` to find a client by its exact name. With neither, the sales channel's default client is used. The contact fields, such as `Name` and `EmailAddress`, go on the order.
* **Order numbers:** `OrderNumber` and `OrderReference` are saved together as the client's order number, such as "WEB-10045 - PO 7781".
* **Prices:** A line's `SellingPrice` is used when you send one. Otherwise the price comes from the client's pricelist (the set of selling prices assigned to the client), or the product's default price. Prices aren't converted between currencies.
* **Tax:** Tax comes from the client's tax setup in OrderEazi, not from the request.
* **Stock and warehouses:** Each line is split across the sales channel's warehouses, in the order the sales channel lists them, by the stock each has. Anything not in stock goes on the first warehouse, to be bought in.
* **Key values and tags:** `KeyValues` (custom fields) are saved on the project, so you can find the project by them later. Each tag must be 3 to 128 characters.
* **Serial numbers:** A product with serial numbers needs a `SerialNumbers` entry for each unit.

### What happens after the order arrives

1. OrderEazi creates the project on the sales channel's workflow, with its sales rep.
2. The lines are added and split across the channel's warehouses.
3. If you sent a `ShippingRequest`, the courier is booked. See [Shipments](/central/developers/api-guides/shipments.md).
4. If the sales channel has **Auto Approve** on, the order is approved, and the Sales Order is created.

If the order can't be approved, it's still created, and `SalesOrderNumber` is empty or holds a message saying why. Check `SalesOrderNumber` in each response, and follow up any unapproved order in OrderEazi.

### When an order is refused

* **"Unknown sales channel selected":** The name in the path doesn't match a sales channel exactly. Check it against **Integrations** > **Sales Channels**.
* **"This sales channel has no fulfillment warehouses configured.":** Ask the organisation to add a warehouse to the sales channel.
* **"No lines to create for the order.":** Send at least one line.
* **A serial number message:** The number of `SerialNumbers` must match the line's `Quantity`.

> **Warning:** Sending the same order twice creates it twice. If a call times out, search for the project by its order number before you send the order again. See [Projects and documents](/central/developers/api-guides/projects-and-documents.md).

### How to cancel an order

Send a PATCH to `/api/order/{channel}`:

```json
{
  "ProjectNumber": "PRO001234",
  "Reason": "Client Cancelled",
  "ReasonMessage": "The client ordered the wrong colour."
}
```

* **`ProjectNumber` or `OrderNumber`:** Send one. The project number is the surest way to find the order.
* **`Reason`:** This is one of `Backordered Too Long`, `Buyer Cancelled`, `Client Cancelled`, `Data Entry Error`, `Duplication`, `Wrong Item Ordered`, or `Other`.
* **`ReasonMessage`:** This is a note of 10 to 1,024 characters.

Cancelling voids the Sales Order, credits any Tax Invoices, and sets the project to Cancelled. It doesn't cancel a courier booking. You can't cancel an order that's been dispatched or completed.

### How to book a courier for an order

To book a courier for an order that's already in OrderEazi, send a POST to `/api/order/ship`. Each parcel lists the order lines it carries, by their `ProjectLineId` from `GET /api/project/{pro}/lines`, where `{pro}` is the project number. See [Shipments](/central/developers/api-guides/shipments.md).

### Related pages

* [Shipments](/central/developers/api-guides/shipments.md): courier quotes and bookings
* [Webhooks](/central/developers/webhooks.md): hear when the order moves on
* [Sales Channels](/central/order-management/integrations/sales-channels.md): set up the sales channel