Hepsiburada API Integration with Odoo: Complete Setup Guide

Turkey's ecommerce landscape features two dominant platforms, and Hepsiburada is the one that every serious seller must master. Established in 2000, Hepsiburada is Turkey's oldest and one of its most trusted online marketplaces, with over 100 million monthly visits, 65,000+ sellers, and a product catalogue spanning every consumer category from electronics and fashion to automotive parts and industrial supplies. For sellers running their operations on Odoo ERP, integrating with Hepsiburada through its robust API is the path to efficient, scalable selling in the Turkish market.

Key Takeaways

• Hepsiburada receives 100 million+ monthly visits and is Turkey's most-visited marketplace
• The platform hosts 65,000+ sellers with 50+ million product listings
• Hepsiburada went public on NASDAQ in 2021, demonstrating institutional-grade marketplace infrastructure
• The HepsiBurada API (HBAPI) provides comprehensive integration endpoints for products, orders, inventory, and claims
• ECOSIRE's connector handles Turkish localisation, KDV tax compliance, and multi-cargo integration
• API-integrated sellers achieve 40% faster order processing and 90% fewer inventory errors

---

Why Hepsiburada Matters

While Trendyol leads in fashion and daily order volume, Hepsiburada holds distinct advantages in electronics, appliances, automotive, and industrial categories. The platform's reputation for consumer trust — built over 25 years of operation — gives it a loyal customer base that overlaps with but differs from Trendyol's audience. Most successful Turkish ecommerce sellers operate on both platforms, making Hepsiburada integration alongside Trendyol a standard requirement.

Hepsiburada Statistics (2025-2026)

Hepsiburada's Competitive Position

Hepsiburada differentiates through:

• Trust: 25 years of operation have built deep consumer trust, particularly for high-value purchases
• Electronics strength: Leading market share in consumer electronics, computing, and mobile devices
• HepsiJet logistics: In-house logistics network with same-day delivery in major cities
• HepsiPay: Integrated payment system with instalment options (critical in Turkey's instalment-driven market)
• Corporate sales: B2B marketplace segment for business purchasing
• Hepsiglobal: Cross-border selling programme reaching international markets

---

Hepsiburada API (HBAPI) Deep Dive

Hepsiburada provides a well-structured REST API that enables comprehensive seller integration. The API documentation is available in English (unlike some Turkish platform APIs), making it accessible to international development teams.

API Architecture

The HBAPI is organised into service domains:

Listing Service

• Create product listings with full attribute sets
• Manage variants (colour, size, model, capacity)
• Handle image upload and ordering
• Map to Hepsiburada's category taxonomy
• Manage listing status (active, passive, locked)
• Handle barcode (GTIN/EAN) requirements

Order Service

• Retrieve new orders (packable orders)
• Access order details (line items, quantities, addresses)
• Update order line status (picking, invoiced, shipped)
• Create packages and assign cargo companies
• Handle partial fulfilment (shipping available items first)

Inventory Service

• Update stock quantities per listing per warehouse
• Set availability status
• Handle multi-warehouse stock allocation

Claims Service

• Process buyer claims (wrong item, damaged, missing)
• Submit claim responses with evidence
• Track claim outcomes and financial impact

Financial Service

• Access settlement reports
• View commission breakdowns
• Track penalty and adjustment deductions
• Download invoices and financial documents

Authentication

HBAPI uses HTTP Basic Authentication with a merchant ID, username, and password provided through the Hepsiburada Merchant Panel. Some endpoints require additional IP whitelisting for security.

Rate Limits and Best Practices

• Standard rate limits: 100 requests per minute per endpoint
• Inventory updates: Batch operations recommended (up to 100 SKUs per request)
• Order polling: Recommended every 10 minutes
• Product creation: Limited to 500 new listings per hour during peak periods

---

Integration Architecture

Order Processing Pipeline

Hepsiburada's order lifecycle differs slightly from other marketplaces. Orders go through a specific state machine:

New → Picking → Invoiced → Packaged → Shipped → Delivered
  ↓        ↓         ↓          ↓
Cancel  Re-stock  [Skip if    Tracking
                   digital]    Push

The integration must respect this state machine — skipping states or updating out of sequence causes API errors and potential order processing failures.

Component 1: Product Listing Integration

Creating and managing listings on Hepsiburada requires attention to platform-specific requirements:

• Category attributes: Each category has mandatory and optional attributes. Electronics require brand, model, technical specs, and warranty period. Fashion requires size chart, material, and care instructions
• Barcode requirement: All physical products must have valid GTIN/EAN barcodes. The integration must validate barcode format before submission
• Image requirements: Minimum 500x500 pixels, white background for main image, up to 8 images per listing
• Brand verification: Brands must be approved on Hepsiburada before products can be listed. The integration should check brand approval status before attempting listing creation
• Content language: All listing content must be in Turkish for the domestic marketplace

The connector maps Odoo product data to Hepsiburada's listing format, validates mandatory attributes, and handles image format conversion.

Component 2: Order Import and State Management

The connector polls HBAPI for new packable orders and creates Odoo sale orders with:

• Full product and variant mapping
• Customer shipping address
• Order-level and line-level IDs for state update tracking
• Payment method information
• Delivery SLA requirements

State updates follow Hepsiburada's required sequence:

1. Picking: Confirm order receipt and start warehouse processing
2. Invoiced: Generate and register invoice (required before packaging)
3. Packaged: Create package with dimensions, weight, and assigned cargo company
4. Shipped: Push cargo tracking number

Each state transition calls the HBAPI with appropriate data, and the connector handles retries for transient failures.

Component 3: Inventory Management

Stock availability is pushed from Odoo to Hepsiburada via batch API calls:

• Per-SKU stock quantities updated every 15-30 minutes
• Safety buffers applied for multi-channel sellers
• Zero-stock items automatically deactivated on Hepsiburada
• Stock restoration triggers automatic reactivation

Coordinating Hepsiburada inventory with other sales channels requires the centralised approach described in our real-time inventory sync guide.

Component 4: Cargo and Logistics

Hepsiburada supports multiple cargo options:

• HepsiJet: Hepsiburada's own logistics network (same-day delivery in major cities)
• Yurtic Kargo: Turkey's largest cargo carrier
• Aras Kargo: Nationwide coverage with competitive pricing
• MNG Kargo: Strong in corporate and bulky item delivery
• Surat Kargo: Budget-friendly option for standard deliveries
• UPS Turkey: For international and premium deliveries

The connector integrates with Odoo's shipping module to assign the appropriate carrier based on configurable rules (product category, destination, weight, urgency) and pushes tracking information to Hepsiburada.

Component 5: Claims and After-Sales

Hepsiburada's claims system handles buyer disputes:

• Wrong item: Buyer received a different product than ordered
• Damaged: Product arrived damaged
• Missing items: Incomplete order delivery
• Quality: Product does not match listing description

The connector imports claims into Odoo's helpdesk module, enabling your customer service team to review evidence, submit responses, and track outcomes — all from within Odoo. Claims resolution quality impacts seller score, making efficient handling critical.

Component 6: Financial Settlement

Bi-weekly settlements include:

• Gross sales revenue per order line
• Category-specific commissions (6-18%)
• HepsiJet logistics fees
• Service charges (listing, transaction)
• Penalty deductions (late shipment, cancellation, claim losses)
• Promotional contributions

The connector creates detailed journal entries for each settlement component, enabling accurate per-product and per-category profitability analysis in Odoo.

---

Setup Guide

Step 1: Hepsiburada Merchant Account

1. Register on Hepsiburada Merchant Panel
2. Complete identity and tax verification
3. Request API access and receive credentials (merchant ID, username, password)
4. Submit IP whitelist for API access
5. Request brand approvals for your product brands

Step 2: Odoo Configuration

1. Turkish localisation: Install Turkey-specific accounting, tax, and document modules
2. Currency: Configure TRY with automated exchange rate updates
3. KDV (VAT) setup: Configure tax rates (1%, 10%, 20%) per product category
4. Sales channel: Create "Hepsiburada" sales team
5. Customer: Create "Hepsiburada Marketplace" customer record
6. Carriers: Configure HepsiJet and approved cargo companies in Odoo delivery module
7. Accounts: Create expense accounts for commissions, logistics fees, and penalties

Step 3: Install the ECOSIRE Connector

Deploy the ECOSIRE Hepsiburada connector:

1. Install through Odoo Apps
2. Navigate to Settings > Hepsiburada Integration
3. Enter merchant ID, API username, and password
4. Configure IP whitelist if required
5. Set sync intervals:
   • Orders: every 10 minutes
   • Inventory: every 15 minutes
   • Products: every 4 hours or manual
6. Map product categories to Hepsiburada's taxonomy

Step 4: Product Listing Configuration

1. Map Odoo products to Hepsiburada categories with mandatory attributes
2. Verify GTIN/EAN barcodes for all products
3. Prepare Turkish-language product content
4. Upload compliant product images
5. Set TRY pricing with commission-aware margins
6. Sync initial catalogue and monitor listing approval

Step 5: Order Workflow Setup

1. Configure order import and state management
2. Set warehouse assignment rules for Hepsiburada orders
3. Configure invoice generation (required before packaging in Hepsiburada flow)
4. Set up cargo assignment rules
5. Test end-to-end order processing

Step 6: Financial Setup

1. Map commission rates per product category
2. Configure settlement import schedule
3. Set up fee-specific expense accounts
4. Define reconciliation tolerance for minor variances

---

Hepsiburada-Specific Challenges

Challenge 1: Invoice-Before-Package Requirement

Hepsiburada requires sellers to generate an invoice before creating a shipping package — a sequence that differs from most marketplaces where invoicing happens after or simultaneously with shipping.

Solution: The connector automates the invoice generation step in Odoo, creating and registering the invoice as soon as picking is confirmed. This ensures the correct state sequence (Picking > Invoiced > Packaged > Shipped) is always followed.

Challenge 2: Instalment Payment Culture

Turkey has a strong instalment payment culture — consumers frequently pay for purchases in 3, 6, 9, or 12 monthly instalments. While Hepsiburada and HepsiPay manage the consumer instalment relationship, sellers receive the full payment (minus commissions) according to normal settlement terms.

Solution: The connector correctly records the full payment amount in Odoo regardless of the consumer's instalment plan. The instalment structure is recorded for informational purposes but does not affect the seller's accounting treatment.

Challenge 3: Hepsiglobal Cross-Border Complexity

Hepsiburada's Hepsiglobal programme enables cross-border selling, introducing multi-currency pricing, international shipping logistics, and customs documentation requirements.

Solution: The connector supports Hepsiglobal with separate pricing configurations per target market, international carrier integration, and customs documentation generation through Odoo.

Challenge 4: High Competition in Electronics

Electronics is Hepsiburada's strongest category, but it is also the most competitive. Price sensitivity is extreme, and Buy Box competition requires real-time pricing responsiveness.

Solution: The connector supports pricing rules that adjust based on competitive position and margin floors. Pricing updates can be triggered more frequently for high-competition categories while maintaining profitability guardrails.

Challenge 5: Seasonal Demand Spikes

Turkish ecommerce sees major demand spikes during 11.11 (Singles' Day), Black Friday, and pre-Ramadan shopping periods. Order volumes can increase 3-5x during these events.

Solution: The connector supports peak-mode configurations with increased sync frequency, larger safety buffers, and automated capacity alerts. Pre-event checklists ensure inventory, pricing, and fulfilment capacity are prepared before demand spikes.

---

Manual vs ECOSIRE Connector

---

Dual-Platform Strategy: Hepsiburada + Trendyol

Most successful Turkish ecommerce sellers operate on both Hepsiburada and Trendyol simultaneously. The two platforms have different strengths:

• Hepsiburada: Stronger in electronics, appliances, B2B. Older, higher-income demographic
• Trendyol: Stronger in fashion, beauty, grocery. Younger, mobile-first demographic

Running both from Odoo requires:

1. Unified inventory: Single stock pool allocated across both platforms with safety buffers
2. Platform-specific pricing: Different commission rates and competitive dynamics per platform
3. Separate performance tracking: Each platform has its own seller score algorithm
4. Consolidated reporting: Cross-platform revenue, margin, and performance comparison

The ECOSIRE connector supports multi-platform Odoo configuration, and our multi-marketplace management guide covers the operational strategy in detail.

---

ECOSIRE Integration Services

ECOSIRE's Odoo integration services provide complete support for Hepsiburada sellers:

• End-to-end connector deployment and configuration
• Turkish localisation (KDV, accounting, e-invoice)
• Custom fulfilment workflow design
• Cargo carrier integration and optimisation
• Dual-platform setup (Hepsiburada + Trendyol from one Odoo)
• Staff training and ongoing support

Browse ECOSIRE's marketplace connector catalogue for all available integrations.

---

Frequently Asked Questions

Does the connector support HepsiJet and other Turkish cargo companies?

Yes. The connector integrates with HepsiJet, Yurtic Kargo, Aras Kargo, MNG Kargo, Surat Kargo, and UPS Turkey. Carrier assignment is rule-based (you configure rules for product category, weight, destination, and urgency), and tracking numbers push to Hepsiburada automatically from Odoo's delivery module.

How are Turkish taxes (KDV) handled?

The connector maps Hepsiburada product categories to the correct KDV rate (1%, 10%, or 20%). Invoices generated in Odoo carry the appropriate tax calculations, and settlement reconciliation validates tax amounts against Hepsiburada's records. The Turkish e-invoice (e-Fatura) format is supported for regulatory compliance.

What happens if the API call fails during order state update?

The connector implements retry logic with exponential backoff for transient API failures. If a state update fails after retries, the order is flagged in Odoo for manual attention, and an alert is sent to the configured operations contact. The system tracks API reliability metrics to identify systemic issues.

Which Odoo versions are supported?

The ECOSIRE Hepsiburada connector supports Odoo 17, 18, and 19 (Community and Enterprise editions). Turkish localisation features are bundled with the module.

---

Conclusion

Hepsiburada's combination of massive traffic, consumer trust built over 25 years, and strong positioning in high-value categories makes it an essential sales channel for any seller targeting the Turkish market. The platform's structured API provides a solid foundation for automation, but the integration must respect Hepsiburada's specific requirements — the order state machine, invoice-before-package workflow, cargo integration, and claims handling all have platform-specific nuances.

Sellers who invest in proper Hepsiburada-Odoo integration gain a compounding advantage: faster order processing improves seller scores, which increases visibility, which drives more orders — a virtuous cycle powered by operational efficiency. Those relying on manual processes find the opposite: slow processing leads to score degradation, reduced visibility, and declining sales.

The path forward is clear. Whether you are establishing your first Hepsiburada presence or scaling an existing operation, connecting the platform to your Odoo ERP through ECOSIRE's purpose-built connector eliminates the operational friction that limits growth and erodes margins.