Create International Shipping API

• Introduction
• Request and Response

Introduction

This API provides an interface to create a new international shipment (import / export) at Aymakan.

Request and Response

This API only accepts POST requests.

Development API End Point URL

https://dev-api.aymakan.com.sa/v2/shipping/create

Production API End Point URL

https://api.aymakan.net/v2/shipping/create

Headers

The following headers should be sent along with the request

• Accept: application/json
• Authorization: Your account security code / Api Token

Request

Below table list the request parameters which can be sent to Shipping Create API for international shipments.

{info} The request parameters should be sent in request body using JSON format.

Service Type Codes

The service type is set automatically based on the countries:

Delivery Duty Type

Products

National Address Structure

When using delivery_national_address or collection_national_address, provide an object with the following structure:

{warning} To be compatible with future API updates and releases, Please use the cities in the Cities API.

International Metadata

When creating international shipments, you can attach additional data via international_metadata.

{tip} Upload the file first via Paperless Document Upload to get the document_id.

A sample POST request body for EPX:

{
    "requested_by": "Test3",
    "declared_value": 1,
    "declared_value_currency": "SAR",
    "reference": "",
    "is_cod": 0,
    "currency": "SAR",
    "delivery_name": "Mohammed",
    "delivery_email": "[email protected]",
    "delivery_city": "Dubai",
    "delivery_address": "Sheikh Zayed Road",
    "delivery_neighbourhood": "Al Barsha",
    "delivery_postcode": "00000",
    "delivery_country": "AE",
    "delivery_phone": 971500000000,
    "delivery_description": "",
    "collection_name": "Ahmed",
    "collection_email": "[email protected]",
    "collection_city": "Riyadh",
    "collection_address": "Al Sahafa",
    "collection_neighbourhood": "Riyadh",
    "collection_postcode": 11543,
    "collection_country": "SA",
    "collection_phone": 540000000,
    "collection_description": "",
    "collection_national_address": {
        "short_code": "EFGH5678",
        "building_number": "5678",
        "street_name": "Prince Sultan Road",
        "district": "Al Malaz",
        "city": "Riyadh",
        "post_code": "11564",
        "additional_number": "9012"
    },
    "weight": 38,
    "pieces": 1,
    "items_count": 1,
    "delivery_duty_type": "DDP",
    "products": [
        {
            "sku": "SKU-001",
            "qty": 1,
            "price": 1,
            "price_currency": "SAR",
            "description": "T-shirt",
            "hs_code": "610910",
            "origin_country": "SA"
        }
    ],
    "international_metadata": {
        "tax_identification_number": "id-123",
        "invoice_number": "inv-123",
        "invoice_date": "2025-05-22",
        "document_id": "9b1f6c3e-4d2a-4f0e-8a51-2c7d9e0b1a34"
    }
}

A sample POST request body for IPX:

{
    "requested_by": "Test3",
    "declared_value": 1,
    "declared_value_currency": "SAR",
    "reference": "",
    "is_cod": 0,
    "currency": "SAR",
    "delivery_name": "Ahmed",
    "delivery_email": "[email protected]",
    "delivery_city": "Riyadh",
    "delivery_address": "Riyadh",
    "delivery_neighbourhood": "Al Sahafa",
    "delivery_postcode": 11543,
    "delivery_country": "SA",
    "delivery_phone": 540000000,
    "delivery_description": "",
    "delivery_national_address": {
        "short_code": "ABCD1234",
        "building_number": "1234",
        "street_name": "King Fahd Road",
        "district": "Al Olaya",
        "city": "Riyadh",
        "post_code": "11543",
        "additional_number": "5678"
    },
    "collection_name": "Store",
    "collection_email": "[email protected]",
    "collection_city": "Dubai",
    "collection_address": "Test Street No:10, Test",
    "collection_neighbourhood": "Test",
    "collection_postcode": 34360,
    "collection_country": "AE",
    "collection_phone": 9715320000000,
    "collection_description": "",
    "weight": 2,
    "pieces": 1,
    "items_count": 1,
    "delivery_duty_type": "DDU",
    "products": [
        {
            "sku": "SKU-001",
            "qty": 1,
            "price": 1,
            "price_currency": "SAR",
            "description": "T-shirt",
            "hs_code": "610910",
            "origin_country": "TR"
        }
    ],
    "international_metadata": {
        "tax_identification_number": "id-456",
        "invoice_number": "inv-456",
        "invoice_date": "2025-05-22",
        "document_id": "9b1f6c3e-4d2a-4f0e-8a51-2c7d9e0b1a34"
    }
}

Response

Success Response

Upon successful request, the following response will be sent back with an HTTP status 200 OK.

{
    "success": true,
    "shipping": {
        "reference": null,
        "tracking_number": "EPX2866494373",
        "customer_tracking": null,
        "customer_name": "test Account",
        "requested_by": "Test3",
        "price_set_amount": null,
        "price_set_amount_incl_tax": null,
        "tax_amount": null,
        "tax_rate": null,
        "cod_amount": 0,
        "declared_value": 1,
        "declared_value_currency": "SAR",
        "currency": "SAR",
        "delivery_name": "Mohammed",
        "delivery_email": "[email protected]",
        "delivery_city": "Dubai",
        "delivery_address": "Sheikh Zayed Road",
        "delivery_neighbourhood": "Al Barsha",
        "delivery_postcode": "00000",
        "delivery_country": "AE",
        "delivery_phone": 971500000000,
        "delivery_description": null,
        "collection_name": "Ahmed",
        "collection_email": "[email protected]",
        "collection_city": "Riyadh",
        "collection_address": "Al Sahafa",
        "collection_region": null,
        "collection_postcode": 11543,
        "collection_country": "SA",
        "collection_phone": 540000000,
        "collection_description": null,
        "submission_date": "2021-12-15T12:09:41.915027Z",
        "pickup_date": null,
        "received_at": null,
        "delivery_date": null,
        "weight": 38,
        "pieces": 1,
        "items_count": 1,
        "status": "AWB created at origin",
        "status_label": "AWB created at origin",
        "created_at": "2021-12-15T12:09:41.000000Z",
        "is_reverse_pickup": 0,
        "label": "https://dev.aymakan.com.sa/pdf/generate/172aa74e-980f-4f80-930e-05f465e4cbbc",
        "pdf_label": "https://dev.aymakan.com.sa/pdf/generate/172aa74e-980f-4f80-930e-05f465e4cbbc"
    }
}

{info} The label and pdf_label provides full url to AWB download file in PDF format.

Error Response

In case of an error, the following response can be returned. The error response depends on the validation of request data, make sure all required data is entered correctly.

{
  "message": "The given data was invalid.",
  "errors": {
    "price_set": [
      "The price set field is required."
    ],
    "declared_value": [
      "The declared value field is required."
    ]
  }
}

Also, an HTTP status of 422 Unprocessable Entity will be returned.

In case of invalid credentials 401 Unauthorized, the following response will be returned.

{
    "error": true,
    "response": "Invalid Credentials"
}

{info} Getting this error? See Invalid Credentials for common causes and how to fix it.