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

Schedule Pickup

POST
/api/order/SchedulePickup

SchedulePickup - Schedule pickup for an existing shipment#

Use this endpoint to schedule pickup information for an existing shipment.
This is mainly used when an order was created through PlaceBulk without complete pickup information.
After pickup is scheduled, the shipment can be included in route planning, recipient messaging can be triggered, and the shipping label can be generated.

When to use this endpoint#

  • The order was already created using PlaceBulk.
  • The order does not yet have pickup information.
  • You need to provide the pickup location and service type after order creation.
  • You need to generate the shipping label after pickup details are confirmed.

Required base field#

The following field is always required:
  • trackingNumber - Public tracking number returned when the shipment was created.

Pickup location options#

To schedule pickup, identify the pickup location using one of the options below.

Option 1: Use externalLocationId#

Use this option when you already have a pickup location ID shared between you and Flype.
This is usually the recommended option because it provides faster and more accurate store matching.
Required fields:
  • trackingNumber
  • externalLocationId
  • serviceType
  • merchantName

Option 2: Use pickupLocation#

Use this option when you do not have an externalLocationId.
You must provide the full pickup address details.
Required fields:
  • trackingNumber
  • pickupLocation
  • serviceType
  • merchantName
The pickupLocation object must include:
  • streetAddress1
  • city
  • country
Optional pickup location fields:
  • streetAddress2
  • postalCode
  • latitude
  • longitude

Option 3: Use both externalLocationId and pickupLocation#

You may provide both values if you want pickupLocation to act as a fallback.
The system will first try to find the pickup store using externalLocationId.
If no matching store is found, the system will try to match the store using the provided pickupLocation.
Required fields:
  • trackingNumber
  • externalLocationId
  • pickupLocation
  • serviceType
  • merchantName

Service type#

The serviceType field is required when pickup is being scheduled.
Allowed values:
  • SAME_DAY
  • NEXT_DAY

Merchant name requirement#

merchantName is required whenever externalLocationId or pickupLocation is provided.
The merchantName is used to filter stores by retailer name and make sure the correct pickup store is matched.
Without merchantName, the system cannot accurately identify which retailer store should be used for pickup.

If pickup is already scheduled#

If the shipment already has pickup information from the original PlaceBulk request, you can call this endpoint with only trackingNumber.
In this case:
  • The API returns the existing pickup information.
  • externalLocationId, pickupLocation, serviceType, and merchantName are not required.
  • Any new pickup details sent in the request are ignored.
  • The existing pickup information is not overwritten.

Shipping label behavior#

  • The shipping label is generated only when valid pickup information is available.
  • If the order was created without pickup information, the label will not be created during PlaceBulk.
  • When pickup is later scheduled using this endpoint, the label will be created and returned in the response.
  • If pickup was already scheduled previously, this endpoint returns existing pickup information. In that case, label may be null because no new label is being generated.

Route planning and recipient messages#

A shipment can only be included in route planning after pickup has been scheduled.
Recipient text messages are also sent only after pickup information and service type are available.
To enable routing and recipient messaging, provide either:
  • externalLocationId + serviceType + merchantName
  • pickupLocation + serviceType + merchantName

Common validation cases#

  • If pickup is not already scheduled and no valid pickup location is provided, the API returns a validation error.
  • If an invalid serviceType is provided, the API returns a validation error.
  • If merchantName is missing when externalLocationId or pickupLocation is provided, the pickup store may not be matched correctly.

Summary#

Use SchedulePickup to add pickup details to an existing shipment.
For best results, use externalLocationId with serviceType and merchantName.
If you do not have an externalLocationId, provide the full pickupLocation object with serviceType and merchantName.
Once pickup is scheduled, the shipment can be routed, recipient messaging can be triggered, and the shipping label can be generated.

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
{
    "trackingNumber": "ABC123DEF456",
    "externalLocationId": "LOC123456",
    "serviceType": "SAME_DAY",
    "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/SchedulePickup' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "trackingNumber": "ABC123DEF456",
    "externalLocationId": "LOC123456",
    "serviceType": "SAME_DAY",
    "merchantName": "Store Name"
}'

Responses

🟢200
application/json
Successful response
Body

Examples
{
    "status": "success",
    "data": {
        "trackingNumber": "ABC123DEF456",
        "pickupLocation": {
            "streetAddress1": "123 Main Street",
            "streetAddress2": null,
            "city": "Dubai",
            "country": "United Arab Emirates",
            "postalCode": null,
            "latitude": 25.2772,
            "longitude": 55.2438
        },
        "pickupTime": "2024-01-15T12:00:00.000Z",
        "serviceType": "SAME_DAY",
        "label": "https://storage.googleapis.com/bucket/label/abc123/shippingLabel",
        "externalLocationId": "LOC123456"
    }
}
🟠401
Previous
Bulk Order
Next
Shipment Details
Built with