Create Order - HepsiGlobal Marketplace API

This API documentation outlines the necessary fields and data structures required for managing orders in a marketplace environment. Key financial fields such as order_amount, currency, unit_product_price, total_amount_excl_vat, total_amount, vat_amount, merchant_campaign_amount, marketplace_campaign_amount, and total_discount_amount are expected to be in USD.

If the currency is not USD, additional fields like the exchange rate and those starting with original_ must be provided. Specifically:

exchange_rate: The exchange rate from the original currency to USD. This field is required when the amounts are not in USD. If this field is sent as null, the default exchange rate from the system will be applied.

The API also includes various shipping options, customer details, and structured data for handling complex orders. This comprehensive guide ensures that the full lifecycle of an order is managed efficiently, with special attention to currency handling and conversion.

Request

Body Params application/json

Example

{
    "order_number": "MpOrderNumber1",
    "marketplace": "mp_name",
    "order_date": "2025-03-27T11:20:38+00:00",
    "currency": "USD",
    "original_currency": "AED",
    "original_order_amount": 19.5,
    "currency_rate": 0.272258864,
    "customer": {
        "name": "Customer Name",
        "phone": "+16172531000",
        "email": "global@hepsiburada.com"
    },
    "order_amount": 5.309,
    "shipping_address": {
        "name": "Reciever Name",
        "address": "77 Massachusetts Ave, Cambridge",
        "phone": "+16172531000",
        "email": "global@hepsiburada.com",
        "country_code": "US",
        "district": "Massachusetts",
        "city": "Cambridge",
        "town": "Massachusetts Ave"
    },
    "billing_address": {
        "name": "Billing Customer Name",
        "address": "77 Massachusetts Ave, Cambridge",
        "phone": "+9715000000000",
        "email": "global@hepsiburada.com",
        "country_code": "US",
        "district": "Massachusetts",
        "city": "Cambridge",
        "town": "Massachusetts Ave"
    },
    "order_items": [
        {
            "item_number": "MpOrderItemNumber1",
            "company_id": 11111,
            "spu": "HBC000078KQW3",
            "sku": "HBCV000078KQW4",
            "quantity": 1,
            "unit_product_price": 2.4503,
            "total_amount": 2.4503,
            "original_total_amount": 9,
            "original_currency": "AED",
            "currency": "USD",
            "base_price": 1.06
        },
        {
            "item_number": "MpOrderItemNumber2",
            "company_id": 11111,
            "spu": "HBC000078L5O1",
            "sku": "HBCV000078L5O2",
            "quantity": 1,
            "unit_product_price": 2.8587,
            "total_amount": 2.8587,
            "original_total_amount": 10.5,
            "original_currency": "AED",
            "currency": "USD",
            "base_price": 1.25
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST '/v1/orders' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_number": "MpOrderNumber1",
    "marketplace": "mp_name",
    "order_date": "2025-03-27T11:20:38+00:00",
    "currency": "USD",
    "original_currency": "AED",
    "original_order_amount": 19.5,
    "currency_rate": 0.272258864,
    "customer": {
        "name": "Customer Name",
        "phone": "+16172531000",
        "email": "global@hepsiburada.com"
    },
    "order_amount": 5.309,
    "shipping_address": {
        "name": "Reciever Name",
        "address": "77 Massachusetts Ave, Cambridge",
        "phone": "+16172531000",
        "email": "global@hepsiburada.com",
        "country_code": "US",
        "district": "Massachusetts",
        "city": "Cambridge",
        "town": "Massachusetts Ave"
    },
    "billing_address": {
        "name": "Billing Customer Name",
        "address": "77 Massachusetts Ave, Cambridge",
        "phone": "+9715000000000",
        "email": "global@hepsiburada.com",
        "country_code": "US",
        "district": "Massachusetts",
        "city": "Cambridge",
        "town": "Massachusetts Ave"
    },
    "order_items": [
        {
            "item_number": "MpOrderItemNumber1",
            "company_id": 11111,
            "spu": "HBC000078KQW3",
            "sku": "HBCV000078KQW4",
            "quantity": 1,
            "unit_product_price": 2.4503,
            "total_amount": 2.4503,
            "original_total_amount": 9,
            "original_currency": "AED",
            "currency": "USD",
            "base_price": 1.06
        },
        {
            "item_number": "MpOrderItemNumber2",
            "company_id": 11111,
            "spu": "HBC000078L5O1",
            "sku": "HBCV000078L5O2",
            "quantity": 1,
            "unit_product_price": 2.8587,
            "total_amount": 2.8587,
            "original_total_amount": 10.5,
            "original_currency": "AED",
            "currency": "USD",
            "base_price": 1.25
        }
    ]
}'

Responses

🟢201Created

application/json

Body

Example

{
    "data": {
        "order_number": "11331",
        "order_items": [
            {
                "item_number": "11331-222",
                "status": "open",
                "success": true
            },
            {
                "item_number": "111-222",
                "status": "open",
                "success": true
            }
        ]
    },
    "message": ""
}

🟠422Unprocessable Entity

🟠400Bad Request