> For the complete documentation index, see [llms.txt](https://fincart.gitbook.io/fincart-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fincart.gitbook.io/fincart-api/apis/create-orders-in-bulk.md).

# Create Orders in Bulk

Create up to 50 orders in one call, or up to 500 in the background.

Create many orders in one request. Each item in `orders` uses the same body as [Create New Order](https://fincart.gitbook.io/fincart-api/apis/new-order.md).

Use the synchronous endpoint for up to **50** orders. Use the asynchronous endpoint for up to **500** orders, then follow the batch with polling or a server-sent event stream.

Callers need the orders edit permission. Authorize with the same token from [Generate Access Token](https://fincart.gitbook.io/fincart-api/access/access-token.md).

{% hint style="info" %}
Send `orderDetails.referenceNumber` on every item. If a pending order with that reference already exists, that item returns the existing order instead of creating another one. A repeated reference inside the same batch fails that later item with `DUPLICATE_REFERENCE_NUMBER_IN_BATCH`. One invalid order does not fail the rest of the batch.
{% endhint %}

### Synchronous bulk create

<mark style="color:yellow;">`POST`</mark> `/v4/orders/bulk/create`

Waits until every order in the batch has been processed, then returns one result per item. The HTTP status is **200** even when some orders fail. Maximum **50** orders.

<details>

<summary>Base URL</summary>

<https://api.fincart.io>

</details>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `<token>`          |

**Body**

```json
{
  "orders": [
    {
      "instaShip": false,
      "source": "s2s",
      "orderType": "delivery",
      "courierID": "64e14223c9780561589926c4",
      "customerDetails": {
        "name": "Ahmed Ali",
        "phone": "0100000XXXX",
        "address": {
          "addressLine": "12 El Nasr St, Nasr City",
          "city": "Cairo",
          "area": "Nasr City"
        }
      },
      "orderDetails": {
        "referenceNumber": "S2S-260826-001",
        "paymentType": "with_cash_collection",
        "packageType": "parcel",
        "amount": 350.5,
        "noOfItems": 2,
        "openPackageAllowed": false,
        "description": "T-shirts x2"
      }
    }
  ]
}
```

`orders` must contain at least 1 item and at most 50. A larger or empty batch is rejected with **400** and nothing is created.

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "statusCode": 200,
  "message": "Bulk orders processed",
  "data": {
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0
    },
    "results": [
      {
        "index": 0,
        "referenceNumber": "S2S-260826-001",
        "success": true,
        "status": 201,
        "message": "Order Created Successfully",
        "data": {
          "orderId": "6877b613a665f49134efXXXX",
          "orderCode": "TAC-DR-0000XXXX",
          "shortId": "XXXX",
          "trackURL": "https://fincart.io/t/XXXX",
          "orderStatus": "pending",
          "orderSubStatus": "new",
          "courier": "J&T",
          "courierLogo": "images/jt.png"
        }
      }
    ]
  }
}
```

{% endtab %}

{% tab title="200 (item failed)" %}
The batch still returns **200**. The failed item has `success: false` and an `error` object. `index` is the position of that order in the `orders` array.

```json
{
  "index": 1,
  "referenceNumber": "S2S-260826-002",
  "success": false,
  "status": 400,
  "message": "Duplicated within the submitted batch",
  "error": {
    "errorCode": "DUPLICATE_REFERENCE_NUMBER_IN_BATCH",
    "message": "Duplicated within the submitted batch"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "statusCode": 400,
  "timestamp": "2026-10-18T13:00:00.000Z",
  "path": "/v4/orders/bulk/create",
  "message": "Bad Request Exception",
  "errors": [
    "orders must contain not more than 50 elements"
  ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "statusCode": 403,
  "timestamp": "2026-10-18T13:00:00.000Z",
  "path": "/v4/orders/bulk/create",
  "message": "User is not authorized",
  "errors": [
    "User is not authorized"
  ]
}
```

{% endtab %}
{% endtabs %}

| Result field                | Description                                                                                                     |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `summary.total`             | Orders submitted                                                                                                |
| `summary.succeeded`         | Orders that succeeded                                                                                           |
| `summary.failed`            | Orders that failed                                                                                              |
| `results[].index`           | Position in the submitted `orders` array                                                                        |
| `results[].success`         | `true` when that order was created or an existing pending order was returned                                    |
| `results[].status`          | Status from the single-order create flow. `201` for a new order, `200` when the reference number already exists |
| `results[].data`            | Created order, present when `success` is `true`                                                                 |
| `results[].error.errorCode` | Machine-readable failure code, present when `success` is `false`                                                |

### Asynchronous bulk create

<mark style="color:yellow;">`POST`</mark> `/v4/orders/bulk/create/async`

Accepts up to **500** orders and returns immediately with a `processId`. The batch runs in the background. The body is the same `orders` array as the synchronous endpoint.

**Response**

{% tabs %}
{% tab title="202" %}

```json
{
  "statusCode": 202,
  "data": {
    "processId": "3f1c0c2e-7b1a-4e5d-9c2a-1b6e8f0a4d11"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "statusCode": 400,
  "timestamp": "2026-10-18T13:00:00.000Z",
  "path": "/v4/orders/bulk/create/async",
  "message": "Bad Request Exception",
  "errors": [
    "orders must contain not more than 500 elements"
  ]
}
```

{% endtab %}
{% endtabs %}

{% stepper %}
{% step %}

#### Submit the batch

Call `POST /v4/orders/bulk/create/async` and keep `data.processId`.
{% endstep %}

{% step %}

#### Follow progress

Poll `GET /v4/orders/bulk/create/{processId}/result`, or open the event stream at `GET /v4/orders/bulk/create/{processId}/events`.
{% endstep %}

{% step %}

#### Read the final results

Stop when `status` is `completed` or `failed`. The finished payload includes `summary` and `items`, using the same per-order shape as the synchronous `results` array.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Results stay available for about 5 minutes after the batch finishes. After that, the process id expires and both the poll and the event stream return **404**.
{% endhint %}

#### Poll the result

<mark style="color:yellow;">`GET`</mark> `/v4/orders/bulk/create/{processId}/result`

While the batch is running, the response has counters only. After it finishes, `summary` and `items` are included.

{% tabs %}
{% tab title="200 (running)" %}

```json
{
  "statusCode": 200,
  "data": {
    "status": "running",
    "total": 120,
    "processed": 42,
    "succeeded": 41,
    "failed": 1
  }
}
```

{% endtab %}

{% tab title="200 (completed)" %}

```json
{
  "statusCode": 200,
  "data": {
    "status": "completed",
    "total": 2,
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    },
    "items": []
  }
}
```

`items` uses the same fields as `results` on the synchronous endpoint. A failed batch has `"status": "failed"` and may include `errorMessage`.
{% endtab %}

{% tab title="403" %}

```json
{
  "statusCode": 403,
  "timestamp": "2026-10-18T13:00:00.000Z",
  "path": "/v4/orders/bulk/create/3f1c0c2e-7b1a-4e5d-9c2a-1b6e8f0a4d11/result",
  "message": "You do not have access to this process",
  "errors": [
    "You do not have access to this process"
  ]
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "statusCode": 404,
  "timestamp": "2026-10-18T13:00:00.000Z",
  "path": "/v4/orders/bulk/create/3f1c0c2e-7b1a-4e5d-9c2a-1b6e8f0a4d11/result",
  "message": "Process 3f1c0c2e-7b1a-4e5d-9c2a-1b6e8f0a4d11 not found or expired",
  "errors": [
    "Process 3f1c0c2e-7b1a-4e5d-9c2a-1b6e8f0a4d11 not found or expired"
  ]
}
```

{% endtab %}
{% endtabs %}

#### Listen for events

<mark style="color:yellow;">`GET`</mark> `/v4/orders/bulk/create/{processId}/events`

Server-sent events. Send `Accept: text/event-stream` and the same `Authorization` header. The stream closes after a terminal event.

| Event      | When it is sent                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| `progress` | While the batch is running. Counters only, no per-order items.                                                |
| `done`     | The batch finished. Includes `summary` and `items`.                                                           |
| `failed`   | The batch crashed. May include `errorMessage`.                                                                |
| `result`   | You connected after the batch had already finished. One event with the full snapshot, then the stream closes. |

```
event: progress
data: {"status":"running","total":120,"processed":12,"succeeded":11,"failed":1}

event: done
data: {"status":"completed","total":120,"processed":120,"succeeded":118,"failed":2,"summary":{"total":120,"succeeded":118,"failed":2}}
```

The completion event is `done`. A different merchant receives **403**. An unknown or expired process id returns **404**.
