# Step 3: Managing Your Orders

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tooltip from '_core/components/Tooltip/Tooltip';

This guide walks you through the full FBPI order lifecycle — from receiving a webhook notification to handing the shipment off to noon logistics. By the end, your system will process live orders end to end.

## How It Works

Every FBPI order follows this sequence:

```mermaid
sequenceDiagram
    participant noon as noon
    participant W as Your Webhook
    participant S as Your System
    participant SL as Seller Lab

    noon->>W: POST order notification (order_nr)
    W-->>noon: HTTP 200 (acknowledgment)
    S->>noon: GET /fbpi/v1/fbpi-order/{order_nr}/get
    noon-->>S: Full order details (items, statuses)
    S->>noon: POST /fbpi/v1/fbpi-order/update (mark OOS items, if any)
    noon-->>S: Update confirmed
    S->>noon: POST /fbpi/v1/shipment/create
    noon-->>S: Shipment created
    S->>SL: Create manifest (manual step)
    noon->>W: Pickup from warehouse or you drop off
```

Key points about this flow:

- **Acknowledgment happens at the webhook level.** Returning HTTP 200 to noon's webhook notification is how you acknowledge receipt. noon retries delivery on any non-2xx response.
- **Retrieving full details requires a GET call.** The webhook payload contains only `order_nr`. Call `GetFbpiOrder` to get items, statuses, and pricing.
- **Marking items out of stock is optional.** Only call `UpdateOrder` if some items cannot be fulfilled. Skip it entirely if all items are available.
- **Manifestation is manual.** There is no API for creating manifests. You must complete this step in Seller Lab.
- **Unacknowledged orders become Killed.** If your webhook fails to return HTTP 200 after all retries, noon marks the order as Killed and the partner absorbs the impact.

## Prerequisites

- Active FBPI Integration Warehouse with a webhook URL — see [Warehouse Setup][fbpi/warehouse-setup]
- Stock and pricing pushed for your SKUs — see [Product and Inventory Setup][fbpi/product-inventory]
- Authenticated API session — see [Authenticating Your Requests][authenticating-requests]

---

## Step 1 — Retrieve Your Order Details

When a customer places an order, noon sends a notification to your webhook. Return HTTP 200 immediately, then call `GetFbpiOrder` (`GET /fbpi/v1/fbpi-order/{fbpi_order_nr}/get`) to retrieve the full order.

:::warning
Return HTTP 200 to the webhook as quickly as possible — before any downstream processing. If noon does not receive a 2xx within the timeout window, it will retry, and eventually mark the order as **Killed**.
:::

<Tabs>
<TabItem value="python" label="Python" default>

```python
session = get_authenticated_session()

order_nr = "NFBO123456789"  # extracted from the webhook payload

response = session.get(
    f"https://noon-api-gateway.noon.partners/fbpi/v1/fbpi-order/{order_nr}/get",
    headers={"User-Agent": "MyApp/1.0.0"},
    timeout=30,
)
response.raise_for_status()
order = response.json()
```

</TabItem>
<TabItem value="javascript" label="Node.js">

```javascript
const client = await getAuthenticatedClient();

const orderNr = "NFBO123456789"; // extracted from the webhook payload

const response = await client.get(
    `https://noon-api-gateway.noon.partners/fbpi/v1/fbpi-order/${orderNr}/get`,
    { headers: { "User-Agent": "MyApp/1.0.0" } }
);
const order = response.data;
```

</TabItem>
</Tabs>

**Response:**

```json
<!-- from: v1GetFbpiOrderResponse -->
{
  "fbpi_order_nr": "NFBO123456789",
  "mp_code": "noon",
  "mp_order_nr": "NF123456789",
  "mp_country_code": "ae",
  "customer_country_code": "ae",
  "merchant_code": "STR-12345",
  "currency_code": "AED",
  "warehouse_code": "WH-NOON-001",
  "order_created_at": "2026-04-09T08:42:15Z",
  "items": [
    {
      "mp_item_nr": "NFBO123456789-1",
      "partner_sku": "MY-SKU-001",
      "mp_status": "MP_ITEM_STATUS_CONFIRMED",
      "integration_status": "INTEGRATION_ITEM_STATUS_ACKNOWLEDGED",
      "delivered_invoice_price": 149.99,
      "cancellation_reason_code": null
    }
  ]
}
```

**`mp_status` values** — the marketplace's view of the item:

| Value | Meaning |
|---|---|
| `MP_ITEM_STATUS_CONFIRMED` | Item confirmed and active on the marketplace |
| `MP_ITEM_STATUS_CANCELLED` | Item cancelled by the marketplace |
| `MP_ITEM_STATUS_UNSPECIFIED` | Default — treat as unresolved |

**`integration_status` values** — your integration's view of the item:

| Value | Meaning |
|---|---|
| `INTEGRATION_ITEM_STATUS_ACKNOWLEDGED` | Order received and acknowledged by your webhook |
| `INTEGRATION_ITEM_STATUS_OUT_OF_STOCK` | Item marked out of stock by your integration |
| `INTEGRATION_ITEM_STATUS_SHIPPED` | Shipment created for this item |
| `INTEGRATION_ITEM_STATUS_UNSPECIFIED` | Default — treat as unresolved |

**You'll know this worked when** you receive a response with `items` populated and `integration_status` set to `INTEGRATION_ITEM_STATUS_ACKNOWLEDGED`.

To retrieve customer shipping details, call `GetFbpiOrderCustomerData` (`GET /fbpi/v1/fbpi-order/{fbpi_order_nr}/customer-details/get`). See [GetFbpiOrderCustomerData][fbpi-customer-data].

---

## Step 2 — Mark Out-of-Stock Items

If any items in the order cannot be fulfilled, call `UpdateOrder` (`POST /fbpi/v1/fbpi-order/update`) to mark them as out of stock before creating a shipment. Skip this step if all items are available.

:::warning
Unacknowledged items that are not marked OOS and not shipped within the SLA window cause the order to become **Killed**. A Killed order cannot be recovered.
:::

<Tabs>
<TabItem value="python" label="Python" default>

```python
session = get_authenticated_session()

response = session.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/fbpi-order/update",
    json={
        "fbpi_order_nr": "NFBO123456789",
        "items": [
            {
                "mp_item_nr": "NFBO123456789-2",
                "status": "UPDATE_ORDER_REQUEST_ITEM_STATUS_OUT_OF_STOCK"
            }
        ]
    },
    headers={"User-Agent": "MyApp/1.0.0"},
    timeout=30,
)
response.raise_for_status()
result = response.json()
```

</TabItem>
<TabItem value="javascript" label="Node.js">

```javascript
const client = await getAuthenticatedClient();

const response = await client.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/fbpi-order/update",
    {
        fbpi_order_nr: "NFBO123456789",
        items: [
            {
                mp_item_nr: "NFBO123456789-2",
                status: "UPDATE_ORDER_REQUEST_ITEM_STATUS_OUT_OF_STOCK"
            }
        ]
    },
    { headers: { "Content-Type": "application/json", "User-Agent": "MyApp/1.0.0" } }
);
```

</TabItem>
</Tabs>

The `status` field accepts one value: `UPDATE_ORDER_REQUEST_ITEM_STATUS_OUT_OF_STOCK`.

**You'll know this worked when** a subsequent `GetFbpiOrder` call shows the marked items with `integration_status: INTEGRATION_ITEM_STATUS_OUT_OF_STOCK`.

For the full schema, see [UpdateOrder][update-fbpi-order].

---

## Step 3 — Create a Shipment

Call `CreateShipment` (`POST /fbpi/v1/shipment/create`) to register each shipment with noon. Include the noon-issued <Tooltip content="Airway Bill — a tracking code assigned to each shipment">AWB</Tooltip> for each package.

**Getting an AWB:** Call `GetNoonLogisticsAWBs` (`POST /fbpi/v1/shipment/noon-logistics-awbs/get`) to get AWB numbers from noon. You can request them in bulk (e.g. 500 at a time) for pre-allocation, or one per shipment.

<Tabs>
<TabItem value="python" label="Python" default>

```python
session = get_authenticated_session()

response = session.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/shipment/create",
    json={
        "warehouse_code": "WH-NOON-001",
        "integration_shipment_nr": "SHIP-2026-001",
        "fbpi_order_nr": "NFBO123456789",
        "awbs": [
            {
                "courier": "noon",
                "awb_nr": "AWB123456789"
            }
        ],
        "items": [
            {
                "mp_item_nr": "NFBO123456789-1"
            }
        ]
    },
    headers={"User-Agent": "MyApp/1.0.0"},
    timeout=30,
)
response.raise_for_status()
result = response.json()
```

</TabItem>
<TabItem value="javascript" label="Node.js">

```javascript
const client = await getAuthenticatedClient();

const response = await client.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/shipment/create",
    {
        warehouse_code: "WH-NOON-001",
        integration_shipment_nr: "SHIP-2026-001",
        fbpi_order_nr: "NFBO123456789",
        awbs: [
            {
                courier: "noon",
                awb_nr: "AWB123456789"
            }
        ],
        items: [
            {
                mp_item_nr: "NFBO123456789-1"
            }
        ]
    },
    { headers: { "Content-Type": "application/json", "User-Agent": "MyApp/1.0.0" } }
);
```

</TabItem>
</Tabs>

Key request fields:

| Field | Type | Description |
|---|---|---|
| `warehouse_code` | string | Your integration warehouse code |
| `integration_shipment_nr` | string | Your internal shipment ID — no specific format required |
| `fbpi_order_nr` | string | The FBPI order number from Step 1 |
| `awbs[].courier` | string | `"noon"` for noon logistics, or your courier's name |
| `awbs[].awb_nr` | string | AWB number from GetNoonLogisticsAWBs or your courier |
| `items[].mp_item_nr` | string | Marketplace item number for each item in this shipment |

**Response:**

```json
<!-- from: FbpiService_CreateShipment 200 response -->
{}
```

A successful `CreateShipment` call returns HTTP 200 with an empty body — the status code is the success signal. The response carries no shipment identifier, so use the `integration_shipment_nr` you supplied (or `fbpi_order_nr`) to look the shipment up afterwards.

**You'll know this worked when** a subsequent `GetShipment` call returns the shipment with a confirmed AWB. See [GetShipment][fbpi-get-shipment].

If a shipment must be cancelled, use [CancelShipment][fbpi-cancel-shipment].

---

## Step 4 — Complete the Manifest

Once shipments are created, they appear as pending in Seller Lab. noon will not schedule a pickup until you create a manifest. There is no API for this step — complete it manually in Seller Lab.

1. Log in to [noon Partner Platform][noon-partner-platform].
2. Click the menu icon (☰) at the top left and select **Fulfilled by Partner → Manifestation**.

![Manifestation Navigation][fbpi/manifestation-navigation]

3. Select your warehouse.

![Select Warehouse][fbpi/manifestation_1]

4. Click **Create Manifest**.

![Create Manifest Button][fbpi/manifestation_2]

5. Enter the number of shipments you are handing over and click **Save Changes**.

![Manifestation Creation][fbpi/manifestation_3]

:::info
We are working on an automatic manifestation option that will make this step optional.
:::

**You'll know this worked when** the manifest appears as confirmed in Seller Lab and the shipments are no longer in pending status.

---

## Step 5 — Pack and Hand Over

**Packing:** Pack the order in noon-approved packaging material and print the shipment label returned by `GetShipment`. Affix the label to the package.

**Handover:** noon collects based on the handover preference you selected during warehouse setup:

- **Pickup** — noon's courier collects from your warehouse based on processing time, manifestation data, and your handover settings.
- **Drop-off** — you deliver the packages directly to a noon logistics hub.

Once handed over, the shipment status updates automatically in the noon system.

---

## Testing

Use `CreateSandboxOrder` (`POST /fbpi/v1/sandbox-order/create`) to place a test order against your warehouse without involving a real customer.

<Tabs>
<TabItem value="python" label="Python" default>

```python
session = get_authenticated_session()

response = session.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/sandbox-order/create",
    json={
        "warehouse_code": "WH-NOON-001",
        "idempotency_key": "test-001",
        "items": [
            {
                "status": "MP_ITEM_STATUS_CONFIRMED",
                "partner_sku": "MY-SKU-001"
            }
        ],
        "country_code": "ae"
    },
    headers={"User-Agent": "MyApp/1.0.0"},
    timeout=30,
)
response.raise_for_status()
sandbox_order = response.json()
# sandbox_order["fbpi_order_nr"] — use this to run the full order flow
```

</TabItem>
<TabItem value="javascript" label="Node.js">

```javascript
const client = await getAuthenticatedClient();

const response = await client.post(
    "https://noon-api-gateway.noon.partners/fbpi/v1/sandbox-order/create",
    {
        warehouse_code: "WH-NOON-001",
        idempotency_key: "test-001",
        items: [
            {
                status: "MP_ITEM_STATUS_CONFIRMED",
                partner_sku: "MY-SKU-001"
            }
        ],
        country_code: "ae"
    },
    { headers: { "Content-Type": "application/json", "User-Agent": "MyApp/1.0.0" } }
);
const sandboxOrder = response.data;
// sandboxOrder.fbpi_order_nr — use this to run the full order flow
```

</TabItem>
</Tabs>

Key notes for `CreateSandboxOrder`:

- `idempotency_key` must be unique per test run and at most 10 characters.
- `partner_sku` is optional — the server assigns a dummy value if omitted.
- `country_code` defaults to `"ae"` if omitted.

**Running the test:**

1. Call `CreateSandboxOrder` — your webhook receives a notification with the returned `fbpi_order_nr`.
2. Confirm your webhook returns HTTP 200.
3. Call `GetFbpiOrder` with the sandbox `fbpi_order_nr` and verify the response includes all expected fields.
4. Run the acknowledgment and shipment steps as you would in production.
5. Check the [FBPI Orders Dashboard][fbpi/dashboard] — the sandbox order should show a successful webhook acknowledgment and a created shipment.

**Common failures:**

| Symptom | Likely cause | What to do |
|---|---|---|
| Webhook never fires | Warehouse not active or webhook URL misconfigured | Check warehouse status in Seller Lab |
| `GetFbpiOrder` returns 404 | Order not yet created or wrong `fbpi_order_nr` | Wait a few seconds and retry |
| Shipment creation fails | AWB already used or invalid `mp_item_nr` | Use a new AWB from `GetNoonLogisticsAWBs`; verify item numbers match |
| Order shows as Killed | Webhook timed out or returned non-2xx | Check webhook logs; ensure your endpoint responds within the timeout |

---

## Next Steps

- [Webhook Order Data][fbpi/webhook-order-data] — full reference for parsing the webhook payload and calling the order data APIs
- [FBPI Orders Dashboard][fbpi/dashboard] — monitor webhook attempts, acknowledgments, and shipment events
- [GetFbpiOrder API Reference][get-fbpi-order] — full response schema
- [CreateShipment API Reference][fbpi-create-shipment] — full request and response schema
- [CreateSandboxOrder API Reference][fbpi-sandbox-order] — full sandbox order schema