Shipping

Introduction

The shipping feature is an added value that allows you to simply sell and ship your product through the MyFatoorah platform with only one payment invoice for your customer. You can create your shipping invoice directly without having your products predefined at the MyFatoorah portal account. You just need to share your product information with our API with the exact dimensions and weight, then we take care of the rest.

Currently, we support both DHL and Aramex.

❗️

Approval is needed!

Kindly, contact your account manager or sales representative to activate the Shipping feature.

🚧

Arabic Letters

DHL and Aramex do not support Arabic item names or descriptions.

How it works

📘

Portal account

Before you start, you need to set up your company shipping information in your portal account as described in the Shipping Information section.

Kindly, follow the below steps to fulfill the shipping integration in your system:

1. Call GetCountries endpoint to get a list of all countries that are supported by the shipping module.

2. Call GetCities endpoint to get a list of all cities of a given country code obtained from the step 1 response and the selected shipping method. Example of a GET request is "/v2/GetCities?shippingMethod=1&countryCode=US".

3. Now after you have the country code and city details, you can use them in:

* [SendPayment](doc:send-payment) POST request to create a **MyFatoorah** shipping Invoice. Check the below [send payment example](#sendpayment-with-shipping-sample-message).
* [ExecutePayment](doc:execute-payment) POST request to create an invoice of a selected gateway. Check the below [execute payment example](#executepayment-with-shipping-sample-message).
* [CalculateShippingCharge](doc:calculate-shipping-charge) POST request to display the shipping charge to your customers at cart details page.

1. Use the RedirectURL/PaymentURL from the previous step to make the payment.

2. Once the payment is done successfully, you will be able to download DHL/Aramex AWBl as a PDF in the download section of the receipt.

3. Call GetShippingOrderList endpoint to get a list of order invoice IDs of a given order status and a used shipping method. Example of a GET request is "GetShippingOrderList?shippingMethod=1&orderStatus=0".

4. Call UpdateShippingStatus endpoint, if you need to update the invoice status with the parameter explained in Update Shipping Status. After a successful payment, you have to change the order shipping status to “Prepared” to initiate the shipping. Note that: you can’t change the status to RequestPickup in this API call. If you want to change RequestPickup please follow the below step.

5. Call ApiShipping/RequestPickup?shippingMethod=1 endpoint to get the details about updated order numbers with status. Now it's ready for order status changes. For more details, follow the steps in Request Pickup.

6. Next, use the UpdateShippingStatus endpoint to change another status like "Picked/ Delivered".

SendPayment with Shipping Sample Message

{
  "CustomerName": "name",
  "NotificationOption": "ALL",
  "MobileCountryCode": "965",
  "CustomerMobile": "12345678",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 100,
  "DisplayCurrencyIso": "kwd",
  "CallBackUrl": "https://yoursite.com/success",
  "ErrorUrl": "https://yoursite.com/error",
  "Language": "en",
  "CustomerAddress": {
    "Block": "string",
    "Street": "string",
    "HouseBuildingNo": "string",
    "Address": "address",
    "AddressInstructions": "string"
  },
  "InvoiceItems": [
    {
      "ItemName": "string",
      "Quantity": 20,
      "UnitPrice": 5,
      "Description": "string",
      "Weight": 0.5,
      "Width": 10,
      "Height": 15,
      "Depth": 19
    }
  ],
  "SourceInfo": "string",
  "ShippingMethod": 1,
  "ShippingConsignee": {
    "PersonName": "name",
    "Mobile": "12345678",
    "EmailAddress": "[email protected]",
    "LineAddress": "address",
    "CityName": "DUBAI",
    "PostalCode": "12345",
    "CountryCode": "AE"
  }
}

{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 300050,
        "InvoiceURL": "https://demo.myfatoorah.com/ie/0106230005034",
        "CustomerReference": null,
        "UserDefinedField": null
    }
}

ExecutePayment with Shipping Sample Message

{
  "PaymentMethodId": 1,
  "CustomerName": "test",
  "DisplayCurrencyIso": "kwd",
  "MobileCountryCode": "965",
  "CustomerMobile": "12345678",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 100,
  "CallBackUrl": "https://yoursite.com/success",
  "ErrorUrl": "https://yoursite.com/error",
  "Language": "en",
  "CustomerReference": "string",
  "CustomerCivilId": "string",
  "UserDefinedField": "string",
  "CustomerAddress": {
    "Block": "string",
    "Street": "string",
    "HouseBuildingNo": "string",
    "Address": "Address",
    "AddressInstructions": "Address"
  },
  "InvoiceItems": [
    {
      "ItemName": "name",
      "Quantity": "1",
      "UnitPrice": 100,
      "Description": "string",
      "Weight": 0.5,
      "Width": 10,
      "Height": 15,
      "Depth": 17
    }
  ],
  "ShippingMethod": 1,
  "ShippingConsignee": {
    "PersonName": "name",
    "Mobile": "12345678",
    "EmailAddress": "[email protected]",
    "LineAddress": "address",
    "CityName": "DUBAI",
    "PostalCode": "12345",
    "CountryCode": "AE"
  },
  "SourceInfo": "string"
}

{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 568119,
        "IsDirectPayment": false,
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/Checkout?invoiceKey=030675256811947&paymentGatewayId=20",
        "CustomerReference": "string",
        "UserDefinedField": "string"
    }
}