# 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 %}