# Create New Order

This documentation provides all the details you need to successfully create orders within the Fincart platform. This API enables merchants to specify order details such as customer information, items, shipping preferences, and payment amount. 

## Create Order

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

This end point is to create new shipping order.

<details>

<summary>Base URL</summary>

[https://api.fincart.io](https://api-v3.fincart.io/merchant)

</details>

**Headers**

| Name          | Value                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Content-Type  | `application/json`                                                                                       |
| Authorization | [<mark style="color:blue;">`<token>`</mark>](https://fincart.gitbook.io/fincart-api/access/access-token) |

**Body**

{% tabs %}
{% tab title="Delivery (Standard)" %}

```json
{
  "instaShip": true,
  "source": "s2s",
  "orderType": "delivery",
  "customerDetails": {
    "name": "Clinet Name",
    "phone": "0100000XXXX",
    "address": {
      "addressLine": "Client Address",
      "city": "Cairo",
      "area": "Abdeen - Bab ElLouq",
      "landmark": "Client Landmark" //(Optional, can be empty String) 
    },
    "shippingNotes": "Shipping notes", //(Optional, can be empty String)
    "backupPhone": "0120000XXXX" //(Optional)
  },
  "orderDetails": {
    "paymentType": "with_cash_collection",
    "pickupLocationId": "66f277d401591daadfaeXXX",
    "packageType": "parcel",
    "amount": 4000,
    "noOfItems": 3, //(must be 1 at least)
    "description": "1 X Shoe, 3 X Bags",
    "openPackageAllowed": true,
    "referenceNumber": "#1800022D2", //(Order referance number at your system)
    "serviceType":"standard" //(standard or same-day) 
  }
}
```

{% endtab %}

{% tab title="Delivery (Same-Day)" %}

```json
{
  "instaShip": true,
  "source": "s2s",
  "orderType": "delivery",
  "customerDetails": {
    "name": "Clinet Name",
    "phone": "0100000XXXX",
    "address": {
      "addressLine": "Client Address",
      "city": "Cairo",
      "area": "Abdeen - Bab ElLouq",
      "landmark": "Client Landmark" //(Optional, can be empty String) 
    },
    "shippingNotes": "Shipping notes", //(Optional, can be empty String)
    "backupPhone": "0120000XXXX" //(Optional)
  },
  "orderDetails": {
    "paymentType": "with_cash_collection",
    "pickupLocationId": "66f277d401591daadfaeXXX",
    "packageType": "parcel",
    "amount": 4000,
    "noOfItems": 3, //(must be 1 at least)
    "description": "1 X Shoe, 3 X Bags",
    "openPackageAllowed": true,
    "referenceNumber": "#1800022D2", //(Order referance number at your system)
    "serviceType":"same-day" //(standard or same-day) 
  }
}
```

{% endtab %}

{% tab title="Return" %}

```json
{
  "instaShip": true,
  "source": "s2s",
  "orderType": "return",
  "customerDetails": {
    "name": "Clinet Name",
    "phone": "0100000XXXX",
    "address": {
      "addressLine": "Client Address",
      "city": "Cairo",
      "area": "Abdeen - Bab ElLouq",
      "landmark": "Client Landmark" //(Optional, can be empty String) 
    },
    "shippingNotes": "Shipping notes", //(Optional, can be empty String)
    "backupPhone": "0120000XXXX" //(Optional)
  },
  "orderDetails": {
    "paymentType": "without_cash_refund",
    "returnLocationId": "66f277d401591daadfaeXXX",
    "packageType": "parcel",
    "amount": 0,
    "noOfItems": 3, //(must be 1 at least)
    "description": "1 X Shoe, 3 X Bags",
    "openPackageAllowed": false, //false always with return orders
    "referenceNumber": "#1800022D2", //(Order referance number at your system)
    "serviceType":"standard"
  }
}
```

{% endtab %}

{% tab title="Exchange" %}

```json
{
  "instaShip": true,
  "source": "s2s",
  "orderType": "exchange",
  "customerDetails": {
    "name": "Clinet Name",
    "phone": "0100000XXXX",
    "address": {
      "addressLine": "Client Address",
      "city": "Cairo",
      "area": "Abdeen - Bab ElLouq",
      "landmark": "Client Landmark" //(Optional, can be empty String) 
    },
    "shippingNotes": "Shipping notes", //(Optional, can be empty String)
    "backupPhone": "0120000XXXX" //(Optional)
  },
  "orderDetails": {
    "paymentType": "without_cash_difference",
    "pickupLocationId": "66f277d401591daadfaeXXX",
    "packageType": "parcel",
    "amount": 0,
    "noOfItems": 3, //(must be 1 at least)
    "description": "1 X Shoe, 3 X Bags",
    "openPackageAllowed": false,
    "referenceNumber": "#1800022D2", //(Order referance number at your system)
    "serviceType":"standard"
  }
}
```

{% endtab %}
{% endtabs %}

| Order Type | Allowed Payment Type      | Amount                 |
| ---------- | ------------------------- | ---------------------- |
| `delivery` | `with_cash_collection`    | Must be more than Zero |
| `delivery` | `without_cash_collection` | 0                      |
| `exchange` | `with_cash_collection`    | Must be more than Zero |
| `exchange` | `without_cash_difference` | 0                      |
| `return`   | `without_cash_refund`     | 0                      |

**Response**

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

```json
{
    "statusCode": 201,
    "message": "Order Created Successfully",
    "data": {
        "orderCode": "DMA-EX-0000XXXX",
        "orderId": "6877b613a665f49134efXXXX",
        "externalId": "JEG000336967XXX",
        "courier": "J&T",
        "orderStatus": "pending",
        "orderSubStatus": "new",
        "shortId": "XXXX",
        "trackURL": "https://fincart.io/t/XXXX",
        "courierLogo": "images/jt.png"
    }
}
```

{% endtab %}

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

```json
{
    "statusCode": 201,
    "message": "Order marked as Duplicate. Review in Fincart Action Center.",
    "data": {
        "orderCode": "DMA-DR-0000XXXX",
        "orderId": "6877b613a665f49134efXXXX",
        "orderStatus": "pending",
        "orderSubStatus": "duplicate",
        "shortId": "XXXX",
        "trackURL": "https://fincart.io/t/XXXX",
        "courier": null,
        "courierLogo": null
    }
}
```

{% endtab %}

{% tab title="200(missing tracking)" %}

```json
{
    "statusCode": 201,
    "message": "Order marked as Missing Tracking. Review in Fincart Action Center.",
    "data": {
        "orderCode": "DMA-DR-0000XXXX",
        "orderId": "6877b613a665f49134efXXXX",
        "orderStatus": "pending",
        "orderSubStatus": "missing tracking",
        "shortId": "XXXX",
        "trackURL": "https://fincart.io/t/XXXX",
        "courier": null,
        "courierLogo": null
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "statusCode": 400,
    "timestamp": "2025-07-16T14:35:59.275Z",
    "path": "/v4/orders/create",
    "message": "Bad Request Exception",
    "errors": [
        "Invalid Phone"
    ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
    "statusCode": 403,
    "timestamp": "2025-07-16T14:34:52.643Z",
    "path": "/v4/orders/create",
    "message": "User is not authorized",
    "errors": [
        "User is not authorized"
    ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fincart.gitbook.io/fincart-api/apis/new-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.