1. Shipments
Flype Order API Gulf
  • UAE API Integration Guide
    • Shipments
      • Shipments Count
        GET
      • All Shipments
        POST
      • Create Bulk Orders
        POST
      • Schedule Pickup
        POST
      • Shipment Details
        GET
      • Shipment Last Status
        GET
      • Cancel Shipment
        POST
      • Get AirwayBill
        GET
    • Locations
      • Get Cities
      • Get All Countries
    • Webhook
      • Shipment Status Updates Webhook
    • Schemas
      • Error
      • ServiceType
      • TrackingStatusName
      • PickupLocation
      • RecipientAddress
      • pickupLocation
      • Parcel
  1. Shipments

Create Bulk Orders

POST
/api/order/PlaceBulk

PlaceBulk - Create bulk shipments#

Create multiple shipments in a single request.

Pickup location options#

To generate a shipping label, send an SMS/message to the recipient, and include the shipment in route planning, pickup information must be provided.
You can provide pickup information in one of the following ways:

Option 1: Use externalLocationId - Recommended#

Use a unique pickup location ID shared between you and Flype.
This option is usually best for 3PLs or merchants with fixed pickup locations that do not change often. It provides the most accurate and fastest store matching.
Required fields for this option:
  • externalLocationId
  • serviceType
  • merchantName

Option 2: Use pickupLocation#

Use this option when you do not have an externalLocationId.
This requires the full pickup address details.
Required fields for this option:
  • pickupLocation
  • serviceType
  • merchantName

Important notes#

merchantName is required when either pickupLocation or externalLocationId is provided.
It is used to filter stores by retailer name and ensure that the correct store is matched. Without merchantName, the system cannot accurately identify which retailer store should be used for pickup.
If an order is sent without externalLocationId or pickupLocation, and without serviceType:
  1. The order will not be considered for route planning until pickup is scheduled.
  2. No text message will be sent to the recipient until pickup is scheduled.
  3. No shipping label will be created or returned, because labels require store or pickup location information.

Pickup scheduling#

You must schedule the pickup in one of two ways:
  1. In the PlaceBulk request by including either externalLocationId or pickupLocation, together with serviceType and merchantName.
  2. After the order is created, by using endpoint #4: SchedulePickup.
If pickup is scheduled later using SchedulePickup, the shipping label will be created and returned only when pickup is scheduled.

Items and parcels#

Use the items array to describe the products inside the shipment.
Use the optional parcels array to describe the physical package or packages that will be picked up and delivered.
This separation helps distinguish between product details and package-level handling details such as parcel weight and dimensions.

parcels object#

The parcels field is optional and contains the physical package details for the shipment.
Each object in the array represents one parcel or package.
If the shipment contains multiple physical packages, include one parcel object for each package.
For example, if the shipment has two boxes, provide two objects inside the parcels array.
Parcel fields:
  • weight - Parcel weight in grams. Must be a non-negative number.
  • dimensions - Parcel dimensions object. Optional, but recommended for bulky shipments.
  • dimensions.length - Parcel length in centimeters. Must be a positive number.
  • dimensions.width - Parcel width in centimeters. Must be a positive number.
  • dimensions.height - Parcel height in centimeters. Must be a positive number.
The parcels array is used for package-level shipment handling. It does not replace the items array, which describes the products inside the shipment.
If parcels is not provided, shipment handling will rely on totalOrderWeight and numberOfPieces, if provided.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params application/jsonRequired

Examples
{
    "list": [
        {
            "recipientName": "John Doe",
            "mobileNumber": "123456789",
            "email": "john.doe@example.com",
            "totalCOG": 120.25,
            "shipperRef": "0123456",
            "remarks": "Leave with doorman",
            "address": {
                "street1": "34 Marasi Dr",
                "street2": "APT 28C",
                "city": "Dubai",
                "country": "United Arab Emirates"
            },
            "items": [
                {
                    "itemName": "Product Name",
                    "weight": 150,
                    "quantity": 2
                }
            ],
            "externalLocationId": "LOC123456",
            "serviceType": "SAME_DAY",
            "totalOrderWeight": 3000,
            "merchantName": "Store Name"
        }
    ]
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST '/api/order/PlaceBulk' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "list": [
        {
            "recipientName": "John Doe",
            "mobileNumber": "123456789",
            "email": "john.doe@example.com",
            "totalCOG": 120.25,
            "shipperRef": "0123456",
            "remarks": "Leave with doorman",
            "address": {
                "street1": "34 Marasi Dr",
                "street2": "APT 28C",
                "city": "Dubai",
                "country": "United Arab Emirates"
            },
            "items": [
                {
                    "itemName": "Product Name",
                    "weight": 150,
                    "quantity": 2
                }
            ],
            "externalLocationId": "LOC123456",
            "serviceType": "SAME_DAY",
            "totalOrderWeight": 3000,
            "merchantName": "Store Name"
        }
    ]
}'

Responses

🟢200
application/json
Successful response
Body

Examples
{
    "acceptedOrders": [
        {
            "status": "success",
            "shipperRef": "0123456",
            "trackingNumber": "EHJJ5ZA5PY27",
            "label": "https://storage.googleapis.com/bucket/label/abc123/shippingLabel",
            "pickupTime": "2024-01-15T12:00:00.000Z",
            "serviceType": "SAME_DAY",
            "externalLocationId": "LOC123456"
        }
    ],
    "deniedOrders": []
}
🟠400
🟠401
Previous
All Shipments
Next
Schedule Pickup
Built with