Hepsiburada: marketplace guide

About this guide

This is a ChannelEngine guide on the Istanbul-based marketplace Hepsiburada. Here you can find information on how to request a Hepsiburada account, how to configure this marketplace on ChannelEngine, and what the specific requirements are.

Table of contents

Commercial information

How to request an account

Associated costs

Marketplace features

Settings and configuration

Marketplace-specific requirements and exceptions

• Setup
• Product selection
• Categorization
• Mappings
• Pricing
• Listed products

Additional information

FAQs

Commercial information

*Cross-border fulfilment is possible through HepsiGlobal, but Hepsiburada’s core marketplace operations are Turkey-based.

**Best-performing categories are mobile phones, technology and electronics, home appliances, home and garden, supermarket/FMCG, fashion and lifestyle, and books and hobbies.

How to request an account

To start selling on Hepsiburada, go to the Hepsiburada İş Ortağım (Business Partner) seller panel, select New Application, and choose the seller type that applies to you. Create a store account, complete the online application form, upload the required company and legal documents, approve the seller agreement, and wait for Hepsiburada to review and approve your application.

To become a merchant, you need to be a legally registered business or taxpayer, and you need to provide company, contact, billing, and bank account details along with the required legal documents. You also need to comply with Hepsiburada's category, product listing, fulfillment, and service quality rules.

VAT requirements

Sellers must be registered taxpayers and comply with Turkish VAT rules. You are responsible for issuing valid invoices or e-invoices/e-archive invoices where applicable, applying the correct VAT rate per product category, declaring and remitting VAT to the Turkish tax authorities, and keeping the required tax records.

API authorization

Before you can connect Hepsiburada to ChannelEngine, Hepsiburada needs to authorize the connection. Hepsiburada provides the API secret key directly to you, and you pass it on to ChannelEngine. 

Authorization is a three-step process:

1. Complete the contract process. Send an email to mp_sozlesme@hepsiburada.com stating your request to become an integrator, along with a brief summary of your intended selling operations. The relevant team assists you further.
2. Testing phase. Once the contracts are finalized, you are provided with test environment credentials, and you complete the tests for your intended operations. For questions during the testing phase, contact Hepsiburada at hepsiapi@hepsiburada.com.
3. Go live. After the testing phase is successfully completed, Hepsiburada transitions you to the live environment. Detailed information regarding the authorization processes is provided during this period. 

Associated costs

There is no setup or onboarding cost to open a store on Hepsiburada, and there is no standard monthly fixed fee. Merchants are charged mainly through category-based commissions on completed sales. Additional optional or usage-based fees may apply for logistics, fulfillment, and advertising services.

Commission fees are calculated over the listed product price. Rates vary per category and subcategory; check the current commission table in the Hepsiburada seller panel.

There is no fixed monthly fee to merchants. Optional and usage-based fees apply for services such as logistics (HepsiJET, HepsiLojistik), fulfillment, and advertising (HepsiAd).

Merchant cancelations carry a penalty. See Cancelations for the fee table.

Marketplace features

*A marketplace that supports sales channels allows merchants to list and sell products across multiple markets (e.g.: countries, regions, and states), all from the same connection.

Settings and configuration

Setting up each channel on ChannelEngine follows the same flow, though not every channel includes the steps listed below.

1. Go through the Setup.
2. Create a Product selection.
3. Complete the Categorization.
4. Set up the Mappings: content, offers, and carriers.
5. Configure the Pricing: rules and currency conversion.
6. Fill in the Stock settings.
7. Finish the Activation.
8. Check the Listed products overview.

Marketplace-specific requirements and exceptions

• All categories and attributes imported from Hepsiburada are in Turkish. The category tree contains around 4,957 leaf categories.
• Hepsiburada works with a shared catalog. Content you send can be overwritten by another merchant's values if Hepsiburada judges those values to be better, and your own content updates are reviewed one by one. Approval by the Business Development team takes a few days to a week.
• Hepsiburada works with a packaging system: one order can result in several packages, and every package becomes a separate order on ChannelEngine.
• Two merchant portal settings must be configured before onboarding: automatic packaging and delivery profiles. Without them, ChannelEngine cannot fetch or ship orders. See Setup.
• Hepsiburada only supports the Turkish language, and there are no multiple sales channels.
• Bundles are not supported.

Setup

On Hepsiburada

1. Go to My account, Entegrasyon (Integration), Entegratör Bilgileri (Integrator information), and copy your Mağaza ID (Store ID). This is your API key.

2. Request your API secret key from the Hepsiburada team. Hepsiburada provides it to you directly after authorizing your account.
3. Go to My settings, Automatic packaging, and set Prepare orders for automatic shipping to Yes. This moves new orders from To Be Packed to Ready to Ship automatically. Without this setting, ChannelEngine cannot fetch your orders.
4. Under How should orders be automatically prepared for shipping?, select Prepare as a single package. This collects all items of an order into one package where the cargo companies match, which keeps shipping costs down. Prepare separately creates a package per item and is only sensible for merchants selling digital products, where there is no shipping cost.

5. Go to My account, Delivery profiles, and select Add delivery profile. Create at least one profile. Delivery profiles are mandatory for the shipment process, and the profile name is what you map on ChannelEngine.

On ChannelEngine

Connection

• API key - your Mağaza ID (Store ID) from Entegrasyon (Integration), Entegratör Bilgileri (Integrator information) in the Hepsiburada seller panel.
• API secret key - provided to you by the Hepsiburada team.

Advanced settings

• Use sandbox - set it to Yes to test against Hepsiburada's test environment. Sandbox credentials are separate from production credentials and are issued by Hepsiburada. Testing in the sandbox is not mandatory; you can go straight to production.
• Enable last mile delivery - set it to Yes to generate a common shipping label for all shipment processes. Only HepsiJET and Aras Kargo support shipping labels. Leave it on No if you ship with your own carriers.
• Enable pre-matched products auto approvement - set it to Yes to let ChannelEngine automatically approve products that Hepsiburada has placed in pre-matched status. Set it to No (the default) to review each match yourself in the Hepsiburada seller panel. Yes suits high product volumes; No suits most cases, and it is the right choice if you want your own content to win over reseller content.
• Enable bulk lock remove - set it to Yes to let ChannelEngine automatically remove listing locks (caused by high price, low price, order cancelation, and similar) through the API. The default is No, which keeps price control on your side. See Locked listings.
• Set orders to closed after import - when enabled, new orders from this channel are marked closed and inventory reservation is not updated. Shipments and returns are then not imported or processed.

Product selection

Create your product selection as you would for any other channel. Note that all categories you map in the next step are in Turkish.

Categorization

All categories imported from Hepsiburada are in Turkish.

Category information is mandatory for product creation and determines the data model of the product; the attributes available to you depend entirely on the category you select. 

Mappings

All attributes imported from Hepsiburada are in Turkish.

Content

The number of required attributes depends on the category; most categories ask for five or six attributes.

All products (required)

• Garanti Süresi (Ay) (Warranty period in months) - the warranty duration expressed in months. A two-year warranty is entered as '24'.
• KDV (VAT rate) - the VAT percentage that applies to the product.
• Görsel 1 (Image 1) - the URL of the main product image. See the image requirements below.
• Marka (Brand) - the product brand. It must not be the seller name. Check the original spelling online, and pay attention to capitalization (Lego vs LEGO) and punctuation (Faber Castell vs Faber-Castell). Check whether a duplicate brand already exists on the site (Dr Brown vs Dr. Brown's).
• Ürün Adı (Product name) - the product title. Start with the brand name, then the model number, then the key features (for example, 'Sinbo SCM-2928 Electric Turkish Coffee Maker'). Capitalize the first letter of each word, write model numbers fully in capitals (43HB3456), and express units consistently (cm, kg). Use numerals instead of words, and include quantity where relevant ('Scotch Brite Sponge 24 pcs'). Do not include campaign information, misleading claims, or the seller name.
• Ürün Açıklaması (Product description) - the product description. Every product needs one. Specify the box contents (TV, hanger, HDMI cable), material information (100% cotton, wood), and dimensions where relevant. Separate the text into paragraphs rather than one block. Do not include delivery details, contact information, company names, advertising, company links, or YouTube links.

All products (optional)

• Desi (Volumetric weight) - the volumetric weight of the product, used to calculate shipping cost.
• Görsel 2-10 (Images 2-10) - URLs of additional product images.
• Ürün İçerik Gönderilsin mi? (Export product content) - set it to No to stop ChannelEngine from sending the product for creation and for content updates. Useful when the product already exists in Hepsiburada's shared catalog, and you would rather send only price and stock.
• Video - the URL of a product video. Many categories support video, and it tends to lift conversion in electronics, personal care, and small domestic appliances.

Category-specific

The same attribute can appear in multiple categories but may carry different option values per category. Therefore, map attributes per category rather than assuming a fixed set. Variation attributes such as color and size are category-specific too; there is no fixed attribute across the category tree.

Image requirements

• Use PNG or JPG. GIF is not supported.
• The background must be white or light.
• No text (free shipping, same-day shipping), logos, or watermarks.
• No graphic drawings or illustrations, and no frames.
• No blurry or low-quality images.
• The product must take up 80% of the image.
• One angle or direction per image.
• Show the first image unboxed and unpackaged so all features are visible.
• Do not include elements that are not part of the product, except in lifestyle images.
• After the white background is removed, at least one side of the remaining area must be 250 pixels.
• Only the product offered for sale may appear: no other colors or patterns that are not part of it.

Offer

Offer mappings are optional, but mapping them supports your product quality on the channel. 

All products (optional)

• Allow promotion below min price - set it to ‘true’ to allow the promotion price to drop below your product's minimum price. 
• BT Kargo Firması (BT cargo company) - the carrier designated for Hepsiburada's BT delivery flow. Confirm the applicable value with your Hepsiburada category manager.
• Göndericinin adres satırı (Sender address line) - the label of the warehouse address the shipment is sent from, as defined in the Hepsiburada seller panel (for example, BIRINCIL).
• İade ve talepler için adres satırı (Return and claims address line) - the label of the warehouse address returns and claims are sent to, as defined in the Hepsiburada seller panel.
• Kargo Firması 1 (Cargo company 1) - the primary carrier for the listing. Use Hepsiburada's exact spelling: Yurtiçi Kargo, Aras Kargo, PTT Kargo, Borusan Lojistik, Horoz Lojistik, HepsiJet, MNG Kargo, Sürat Kargo, Ceva Lojistik, UPS, Mağaza Hesabı.
• Kargo Firması 2 (Cargo company 2) - a second carrier for the listing. If you select only HepsiJET in Kargo Firması 1 (Cargo company 1), you must add a standard carrier here; otherwise, Hepsiburada returns a MissingStandardCargoCompany error. The same applies to Horoz and Borusan.
• Kargo Firması 3 (Cargo company 3) - a third carrier for the listing.
• Kargolama Profili (Shipping profile) - the name of the delivery profile the SKU should use. Create the profile first in the Hepsiburada seller panel at My account, Delivery profiles, Profiles you create, then map the name here. Hepsiburada derives the carrier for the order from the profile assigned to the SKU. Offers without a profile are still sent, but Hepsiburada is likely to reject them.
• Kilit Kaldırma Aktif (Lock removal active) - set it to Yes to allow ChannelEngine to unlock this listing when Hepsiburada locks it over a price threshold. This only takes effect when Enable bulk lock remove is also enabled in the Setup step. The default is No. Enabling the channel setting sets this to Yes for all products, and you can override it per product here.
• Kurulum var mı? (Has installation?) - set it to Yes if the product includes an installation service.
• YT Kargo Firması (YT cargo company) - the carrier designated for Hepsiburada's YT delivery flow. Confirm the applicable value with your Hepsiburada category manager.

Carrier

Carrier mappings are not required. Hepsiburada returns the relevant cargo carrier per package based on the package number, so ChannelEngine does not need a carrier list to export a shipment. The carrier list is imported for reference only.

Pricing

ChannelEngine uses pricing v2 on this channel. Map the following in the Pricing step, in Price rules:

• Listing Fiyati (Listing price) - the selling price of the product. Required.
• Kargolama Fiyati (Shipping price) - the shipping cost charged for the product. Optional.

Price validation

The following rules apply when validating your prices:

• Separate kuruş (cents) with a comma and use a maximum of two digits after it, for example 14,50. Prices that do not follow this format are filtered out with a validation message before they reach Hepsiburada.
• Hepsiburada applies category-based threshold values per product. It averages the prices of existing listings, excluding the highest and lowest, and allows a maximum uplift based on that average, as listed in the table below:

Uplift limits on average listing prices

• A price outside that range returns an OutOfPriceRange error. During product creation, the product is made ready for sale with zero stock and zero price instead, and you need to send valid price and stock information to open it for sale.
• Once a product is published, the two-decimal rule is no longer enforced on updates, but the threshold check still applies.
• Thresholds are set by Hepsiburada and can change at any time. They are not officially available in published communication from Hepsiburada.

Listed products

Check the Listed products overview for the status of each offer and for feedback from Hepsiburada. ChannelEngine validates unmapped required attributes itself, and surfaces Hepsiburada's own validation messages here after the product has been sent.

Additional information

Content

Product statuses and matching

Products you send go into one of two states. If Hepsiburada finds the product in its catalog (for example, the same name, GTIN, or images), it goes to the pre-matched state and waits for your approval. If Hepsiburada finds no equivalent, the product goes to the review state.

Pre-matched products stay waiting until you act, either in the Hepsiburada seller panel or through ChannelEngine if Enable pre-matched products auto approvement is enabled. If you reject a match in the seller panel, the process starts again from product creation: resending the same values puts the product back in the pre-matched list, and changing a value (for example, the GTIN) can change the outcome.

Matching existing products

If you already sell on Hepsiburada, you do not need to create your products again. ChannelEngine matches on the merchant SKU. Your ChannelEngine SKU must match the SKU on Hepsiburada. Once matched, ChannelEngine sends price and stock updates from there.

Hepsiburada requires all product SKUs in uppercase and without spaces, so ChannelEngine converts merchant SKUs to uppercase using Turkish culture rules before creating or matching products.

Variations

Hepsiburada supports standalone products and parent/child variations such as color or size. ChannelEngine sends the parent product ID as the variant group ID for variant children, and the product ID for standalone products. The parent product itself is not sent.

Locked listings

If you send a price increase or decrease outside Hepsiburada's threshold values, Hepsiburada locks the SKU, and the listing is taken out of sale. You cannot update the price of a locked listing; it has to be unlocked first.

Unlocking runs through a two-step validation:

1. Enable bulk lock remove must be enabled in the Setup step.
2. Kilit Kaldırma Aktif (Lock removal active) must be enabled in the product's offer attributes.

When both conditions are met, ChannelEngine calls Hepsiburada's lock removal endpoint and the listing reopens with the last submitted price.

Deletes

Product deletion runs through the offer export: ChannelEngine sends a stock quantity of 0. Sending a stock or price value of 0 is another way to close a listing for sale, and sending a non-zero value for both reopens it.

Orders

Order numbers

Hepsiburada works with packages rather than orders: the package becomes the order on ChannelEngine. One Hepsiburada order can contain several packages, and a package can contain several order lines. To keep the order number unique, ChannelEngine builds it as:

Channel order number = order number _ shipment package ID

For example: 1735032345_44564419.

The original Hepsiburada order number is mapped to CommercialOrderNo, which is the reference your local team uses to find the order in the Hepsiburada seller panel.

Addresses

Turkey does not use postal codes for residential addresses. Hepsiburada provides a billing postal code but no shipping postal code, so ChannelEngine uses the billing postal code as the shipping zip code. Addresses arrive as a single line and are mapped to the home address type. You may need to skip address parser validation.

Awaiting payment orders

Not supported.

Order extra data items

When an order is imported to ChannelEngine, ChannelEngine also retrieves extra data items related to the order itself, or to order lines. This extra data is specific to this marketplace. An explanation of each can be found below:

Order extra data

Order line extra data

*Conditional fields are only displayed if the marketplace provides a value.

Cancelations

Marketplace cancelations

Buyers can cancel at any point, including after the shipment has left your warehouse. For shipments sent with HepsiJET, the cancelation option stays available while the parcel is out for delivery. When a buyer cancels, the order status on ChannelEngine switches to Canceled.

Buyers cannot partially cancel; if they bought several units of the same item in one package, they must cancel the whole package.

Merchant cancelations

Merchants can cancel fully or partially, including a single unit of a multi-unit order line. 

Merchant cancelation penalties by product price

Shipments

If the shipping provider is used under a Hepsiburada agreement, all shipping statuses and tracking details (shipping barcode, tracking URL, and tracking number) are transmitted directly to Hepsiburada and to you by the courier company. The same applies to returns: the shipping barcode and tracking information come from the courier. No further action is required from you on this step.

ChannelEngine retrieves the carrier per package from Hepsiburada and sets the order status to Shipped. Carriers update the order statuses themselves from there.

Partial shipments

When orders are partially shipped, ChannelEngine splits the order into separate packages, updates the order and shipment extra data with the new package IDs, retrieves the order again to get the new package numbers, and sets the delivery status for the partially shipped package.

Shipping labels and last-mile delivery

Only HepsiJET and Aras Kargo support shipping labels. Enable Enable last mile delivery in the Setup step to download labels from the Hepsiburada API; labels are returned as ZPL, and the carrier and service are still selected by ChannelEngine. There is no need to retrieve the carrier list through the API. For the exact steps, check out the article Merchant API: shipping labels (last-mile delivery).

For all other carriers, ChannelEngine updates the tracking number on the shipment and the normal shipment flow applies.

Delivery profiles

You need a delivery profile, created in the Hepsiburada seller panel and mapped via the Kargolama Profili (Shipping profile) offer attribute. One package can only carry one delivery profile.

Returns

Only marketplace returns are supported. ChannelEngine imports new returns, and you accept or reject each one via ChannelEngine.

• Returns cover the full shipment (one full order). Returns of individual order lines are not supported, so accept or reject the whole package.
• Merchant returns are not supported: you cannot register that a returned parcel has arrived at your warehouse.
• Buyers create return requests through Hepsiburada's call center. Once accepted, the buyer receives a code and hands the parcel over at a cargo center.
• Hepsiburada does not provide a return label through the integration.

Common errors

FAQs

How often does each task run on Hepsiburada?

*A full offer export runs once per day and covers every field that can be updated on a listing, including carrier, shipping profile, and address label values. The 15-minute exports cover stock and price only.

Do I need to create my products again if I already sell on Hepsiburada?
No. ChannelEngine matches your existing products to your updated offers on merchant SKU. Once a product is matched, ChannelEngine sends price and stock updates straight away. You only need to complete categorization and content mapping for genuinely new products.

Why do I see two orders on ChannelEngine for one Hepsiburada order?
Because ChannelEngine works with Hepsiburada packages, and the package becomes the order. One Hepsiburada order split across two packages arrives as two ChannelEngine orders: same commercial order number, different channel order numbers. Setting Prepare as a single package in the Hepsiburada seller panel keeps most orders to one package.

Why is my listing locked and why can't I update the price?
Hepsiburada locks a listing when the price you send falls outside its category-based threshold for that product. Locked listings are out of sale and cannot accept a price update. Unlock the listing in the seller panel, or enable Enable bulk lock remove in the Setup step together with Kilit Kaldırma Aktif (Lock removal active) on the offer to have ChannelEngine unlock it and reopen the listing at the last submitted price.

Can I stop Hepsiburada overwriting my product content?
Hepsiburada works with a shared catalog and can adopt another merchant's values if it judges them to be better. If you want to keep your own content and send only price and stock, set the Ürün İçerik Gönderilsin mi? (Export product content) attribute to No for those products.

Can I reject a pre-matched product from ChannelEngine?
No. ChannelEngine can only confirm a match. Rejections are done in the Hepsiburada seller panel, where you can also review which values Hepsiburada matched on. Rejecting sends the product back to the start of the creation process.

Do I need carrier mappings?
No, but you do need a delivery profile. Create it in the Hepsiburada seller panel under My account, Delivery profiles, and map the profile name through the Kargolama Profili (Shipping profile) offer attribute. Hepsiburada derives the carrier from the profile.

Can I use the Hepsiburada sandbox for testing?
Yes, but it is optional. Sandbox credentials and account details are entirely separate from production and are issued by Hepsiburada. Roughly 70 to 80% of the integration is testable there: setting an order status to shipped, viewing published products, and creating merchant returns are not. You can go straight to production if you prefer.