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

Introduction

Flype Order API Gulf - Integration Overview#

The Flype Order API Gulf allows partners to check delivery coverage, create shipments, schedule pickups, retrieve shipment information, download airway bills, and receive shipment status updates through webhooks.
This API is designed for merchants, retailers, aggregators, marketplaces, and 3PL partners that want to create and manage Flype delivery orders through a system integration.

Recommended integration flow#

1.
Check service coverage, when possible
Use CheckCoverage before creating an order to check whether the destination address appears to be serviceable. This step is recommended, especially when accurate coordinates are available, but it is not required because some addresses may not be fully verifiable from address details alone.
2.
Create the shipment
Use PlaceBulk to create one or more shipments. Pickup information can be provided during order creation or scheduled later.
3.
Provide pickup information
For best results, include externalLocationId, serviceType, and merchantName when creating the shipment.
If pickup information is not available during order creation, use SchedulePickup later.
4.
Generate or retrieve the airway bill
When valid pickup information is available, Flype can generate the shipping label or airway bill. Use Get AirwayBill if the label needs to be retrieved again.
5.
Track shipment progress
Use Shipment Details for full shipment information, or Shipment Last Status for the latest status only.
6.
Receive status updates automatically
Provide Flype with a webhook URL so shipment status updates can be sent to your system automatically.

Main API sections#

CheckCoverage
Checks whether a destination address appears to be serviceable before order creation. The endpoint evaluates destination coverage, address verification, requested service type, cutoff time, and operating-day rules where applicable.
Shipments Count
Returns summary counts of shipments grouped by operational status. Useful for dashboards and operational monitoring.
All Shipments
Returns a paginated list of shipments filtered by status and date range.
PlaceBulk
Creates one or more shipments in a single request. Each order is processed individually, so the response may include both accepted and denied orders.
SchedulePickup
Adds pickup information to an existing shipment that was created without complete pickup details.
Shipment Details
Returns full shipment information, including recipient details, pickup details, delivery settings, and tracking history.
Shipment Last Status
Returns only the most recent status for a shipment. Use this when full shipment details are not needed.
Cancel Shipment
Cancels a shipment before it has been picked up or entered the active delivery flow.
Get AirwayBill
Retrieves the generated shipping label or airway bill for a shipment.
Locations
Provides country and city reference data that can be used when submitting pickup or delivery addresses.
Webhook
Describes the shipment status update notifications that Flype sends to the partner’s webhook endpoint.

Service coverage behavior#

CheckCoverage is recommended before order creation, but it should not be treated as the only way to determine whether an order can be submitted.
In some Gulf addresses, especially where address formatting is incomplete or inconsistent, the API may not be able to verify the exact location using address details alone. Providing accurate latitude and longitude improves the accuracy of the coverage check.
If valid coordinates are provided, they will be used directly for the coverage check.
If coordinates are not provided or are not usable, Flype will attempt to verify the address using the provided address details.
If the address cannot be verified, the response may return serviceable as null.
A null serviceability result means the API could not make a coverage decision from the provided information. It does not always mean the destination is outside Flype coverage.

Pickup location and merchant identification#

For shipment creation and pickup scheduling, Flype needs to identify both the pickup location and the merchant associated with the shipment.
externalLocationId identifies the physical pickup location, such as a store, warehouse, fulfillment center, or 3PL facility.
merchantName identifies the customer-facing merchant or brand associated with the shipment.
Multiple merchants may share the same pickup location. For this reason, merchantName may be required together with externalLocationId or pickupLocation so Flype can match the shipment to the correct merchant.

Pickup information options#

Pickup information can be provided in one of the following ways:
1.
externalLocationId - recommended
Use a pickup location identifier shared between your system and Flype. This is the recommended option for fixed pickup locations, warehouses, fulfillment centers, aggregators, and 3PL partners.
2.
pickupLocation object
Provide full pickup address details when an externalLocationId is not available.
3.
Schedule pickup later
Create the shipment first without pickup details, then use SchedulePickup to provide pickup information later.

Order creation behavior#

When creating shipments through PlaceBulk, each order is validated and processed separately.
If an order is valid, it is returned in acceptedOrders.
If an order cannot be created, it is returned in deniedOrders with the reason for rejection.
If pickup information is provided, the shipment can be included in route planning and recipient messaging.
If pickup information is missing, the shipment is created but will not be routed, messaged, or labelled until pickup is scheduled.

Airway bill and label behavior#

A shipping label or airway bill can only be generated when the shipment has valid pickup information.
If pickup information is provided in PlaceBulk, the label may be returned during order creation.
If pickup information is scheduled later, the label may be generated and returned by SchedulePickup.
Use Get AirwayBill to retrieve the label again after it has been generated.

Service type#

The serviceType field identifies the requested delivery service. For this Gulf integration, use the service types agreed with Flype during onboarding.
Pickup scheduling, routing, recipient messages, and label generation may depend on a valid serviceType.

Dates and timestamps#

Exact timestamps are returned in UTC ISO 8601 format.
Pickup times such as pickupTime are returned as UTC timestamps.
Local delivery dates, when returned, use YYYY-MM-DD format.
Local operational rules, such as cutoff times and operating days, are evaluated based on the configured local market timezone.

Authentication#

Protected endpoints require a bearer token in the Authorization header.
Authorization: Bearer <token>

Webhook integration#

Flype can send shipment status updates to a webhook endpoint provided by the partner.
The webhook is not an endpoint that the partner calls. Instead, the partner provides Flype with a webhook URL, and Flype sends status update events to that URL when shipment statuses change.

Important notes#

CheckCoverage is recommended but not required before creating shipments.
PlaceBulk creates shipments.
SchedulePickup updates pickup information for an existing shipment.
Get AirwayBill retrieves a label only when the shipment has enough information for label generation.
trackingNumber is the main Flype shipment reference after an order is created.
shipperRef is the partner-provided order or shipment reference.

Best practices#

Use CheckCoverage when possible before PlaceBulk, especially when coordinates are available.
Provide accurate latitude and longitude when available to improve address verification, coverage checks, and routing.
Use externalLocationId whenever possible for reliable pickup matching.
Use a unique shipperRef for every order.
Provide accurate recipient phone numbers so delivery messages and coordination can work correctly.
Use webhooks for automatic shipment status updates instead of repeatedly polling shipment endpoints.
Next
Service Coverage
Built with