eMAG Marketplace

API Documentation v4.4.6

03.10.2023
Version Date modified Changes
4.3.1 05.02.2019 Added new resource for saving volume measurments
Added other currencies option on product_offer/save
Added locker delivery option on order/read and awb/save
Updated the time based throttling for save requests
4.3.2 18.02.2019 Order status matrix update
Important changes in permisions for updating orders (3.5) and removing products from an order (3.5.1)
Added supply_lead_time key on product_offer/save
4.3.4 01.10.2019 Added rate limiting for invalid requests
Added new order cancelation reasons
Added “locker_name” key on order/read
Adjusted the maximum number of elements returned for all read requests
Adjust measurements values decimal length
4.3.5 08.10.2019 Changed the warranty requirement regime
4.3.6 03.12.2019 Part Number input changes
4.3.7 28.09.2020 Added new REST resource for updating stock only
Added new resource for proposing offers in campaigns
4.3.8 13.10.2020 Added new invoice resources
4.3.9 23.11.2020 Added new resource for reading customer invoice data
4.4.0 26.04.2021 Added “source_language” key on product_offer/save for publishing product content in a different language
than the platforms default
4.4.1 28.04.2021 Added voucher discounts distribution on order/read
4.4.2 16.06.2021 Added “detailed_payment_method” key on order/read
Added Draft publishing API details
Changed product ownership logic
4.4.3 08.12.2021 Added new API for reading commission at offer level
Added “return_reason” and “observations” keys at product level on rma/read and rma/save
Changed reading_rma and saving_rma examples (7.4)
4.4.4 09.12.2021 Added “language” parameter on category/read
4.4.5 11.03.2022 Added new filters on locality/read API
Removed “Matching products” section and API
4.4.6 03.10.2023 Additional info on product_offer/read and save
Added new “source_language” values on product_offer/save
Added “emag_club” key on product_offer/save
Added new “validation_status” values on product_offer/read: “Documentation update validation pending” and
“Update rejected”
Added “genius_eligibility” key on product_offer/read
Added “dropoff_locker” key on awb/save
Added “locker_delivery_eligible” key on order/read
Removed the following keys from rma/read and rma/save: “customer_email”, “id” and ”invoice_number”
Added "recycle_warranties" key on order/read
Added new status for offers on product_offer/read and product_offer/save: 2 – End of life
Added additional explanations for offers available for sale
Added “tags” key on category/read
Added “tag” key on product_offer/save (on specific characteristics)
Added new callback: Approved product documentation

2
Table of Contents

1. eMAG Marketplace API.........................................................................................................................................5

1.1. Conventions...........................................................................................................................................................5
1.2. Request, resources and actions.............................................................................................................................6
1.3. Pagination and filters.............................................................................................................................................7
1.4. Response...............................................................................................................................................................7
1.5. Rate limiting..........................................................................................................................................................8
1.6. Callback URLs.........................................................................................................................................................8
2. Publishing products and offers..............................................................................................................................9
2.1. Reading categories, characteristics and family_types...........................................................................................9
2.2. Reading VAT rates...............................................................................................................................................12
2.3. Reading Handling Time values.............................................................................................................................12
2.4. Sending a new product........................................................................................................................................12
2.4.1. Draft product...............................................................................................................................................12
2.4.2. Product........................................................................................................................................................13
2.5. Example for a new product.................................................................................................................................19
2.6. Updating existing offer........................................................................................................................................19
2.7. Saving volume measurements on products.........................................................................................................19
2.8. Reading and counting products and offers..........................................................................................................20
2.9. Product validation responses..............................................................................................................................25
2.10. Attaching offers on existing products..................................................................................................................25
2.11. Reading commission for an offer.........................................................................................................................28
3. Updating stock....................................................................................................................................................28
4. Proposing offers in campaigns.............................................................................................................................29
5. Processing orders................................................................................................................................................30
5.1. Order fields..........................................................................................................................................................30
5.1.1. Product field in order details.......................................................................................................................34
5.1.2. Customer fields in order details...................................................................................................................36
5.1.3. Order invoices..............................................................................................................................................37
5.2. Order notification, acknowledgment and order filters........................................................................................38
5.3. Order status matrix.............................................................................................................................................38
5.4. Order filters.........................................................................................................................................................39
5.5. Updating orders...................................................................................................................................................40
5.5.1. Removing products from an order..............................................................................................................41

3
 5.5.2. Adding products to an existing order..........................................................................................................41
5.5.3. Returned products and storno route...........................................................................................................41
6. Shipping orders...................................................................................................................................................44
6.1. Saving AWB.........................................................................................................................................................44
6.2. Reading AWB.......................................................................................................................................................46
6.3. Reading AWB PDF files........................................................................................................................................47
6.4. Reading AWB ZPL type........................................................................................................................................47
6.5. Counting Localities..............................................................................................................................................48
6.6. Reading Localities................................................................................................................................................48
6.7. Reading courier accounts....................................................................................................................................49
7. Processing return requests..................................................................................................................................50
7.1. Return requests filters.........................................................................................................................................54
7.2. Status change permissions..................................................................................................................................55
7.3. Return request deliveries....................................................................................................................................55
7.4. Examples requests and responses.......................................................................................................................55
8. Invoice API..........................................................................................................................................................55
8.1. Reading invoice categories..................................................................................................................................56
8.2. Reading invoice data...........................................................................................................................................56
8.3. Reading customer invoice data...........................................................................................................................59

4
 1. eMAG Marketplace API
eMAG Marketplace API is developed by eMAG for Marketplace partners in order to allow them to use their own
CRM’s / ERP’s. This document explains the methods for calling the API.
The API can be used in order to:
 send products and offers
 process orders

1.1. Conventions

We define MARKETPLACE_API_URL constant of being the API URL of the platform (ex: https://marketplace-
api.emag.ro/api-3)
We define MARKETPLACE_URL constant of being the URL of the platform (ex: https://marketplace.emag.ro)
We define DEFAULT_CURRENCY constant of being the default currency of the platform (ex: RON).
All API parameters are key-sensitive.

Platform Romania Bulgaria

MARKETPLACE_URL https://marketplace.emag.ro https://marketplace.emag.bg

MARKETPLACE_API_URL https://marketplace-api.emag.ro/api-3 https://marketplace-api.emag.bg/api-3

Protocol HTTPS HTTPS

Locale ro_RO bg_BG

Default currency RON BGN

Platform Hungary

MARKETPLACE_URL https://marketplace.emag.hu

MARKETPLACE_API_URL https://marketplace-api.emag.hu/api-3

Protocol HTTPS

Locale hu_HU

Default currency HUF

To access the API, simply make a Basic Authorization request with your username, password and a base64 computed
hash. Please note that user should be granted API rights in order to access the API.

$hash = base64_encode($username . ':' . $password);

5
 1.2. Request, resources and actions

A Marketplace API call is represented by sending a request to API URL of platform. Every request consists of a POST to an
URL like:

MARKETPLACE_API_URL/resource/action
Ex: https://marketplace-api.emag.ro/api-3/product_offer/save
RESOURCES AND AVAILABLE ACTIONS

Resource Resource URL Available actions

product_offer MARKETPLACE_API_URL/product_offer read save count

measurements MARKETPLACE_API_URL/measurements save

offer_stock MARKETPLACE_API_URL/offer_stock/{resourceId}

campaign_proposals MARKETPLACE_API_URL/campaign_proposals save

order MARKETPLACE_API_URL/api-3/order read save count acknowledge

order/attachments MARKETPLACE_API_URL/order/attachments save

message MARKETPLACE_API_URL/message read save count

category MARKETPLACE_API_URL/category read count

vat MARKETPLACE_API_URL/vat read

handling_time MARKETPLACE_API_URL/handling_time read

locality MARKETPLACE_API_URL/locality read count

courier_accounts MARKETPLACE_API_URL/courier_accounts read

awb MARKETPLACE_API_URL/awb read save

rma MARKETPLACE_API_URL/rma read save

invoice/categories MARKETPLACE_API_URL/api-3/invoice/categories read

invoice MARKETPLACE_API_URL/api-3/invoice read

customer-invoice MARKETPLACE_API_URL/api-3/customer-invoice read

6
Below a code example using the resource "category" and the action "read"

Resource Example Context

http method: POST

category/read

The API needs authorization and has an IP level filtering. Before testing, sellers should provide a list of whitelisted IP’s.
eMAG Marketplace will only allow API calls only from those IP’s.

The POST data consist of 1 mandatory key:

REQUEST

Key Description

data Data to be passed to the API. The following document will describe keys.

1.3. Pagination and filters

In order to limit the number of items returned, read actions accept pagination by passing to POST data following
parameters:

PAGINATION

Key Description Default value Example

currentPage Set current page displayed 1 currentPage =3

itemsPerPage Set number of items to be displayed in one page. Maximum is set to 100. 100 itemsPerPage=50

Also, filters can be included in POST to refine result set. Filters vary depending on the resource called and are exampled
on every resource section.

1.4. Response

When an API call is made, the server MUST reply with a response. The response will ALWAYS be JSON formatted and the
header 'Content-type: application/json' will always be passed.

RESPONSE

Key Description

isError Boolean value representing response status.

messages Messages included in the response, like error messages, etc.

results Results included in the response, mostly when reading resources.

7
IMPORTANT: Every API request must have a response and the response must contain the key “isError” and its value
must be “false”. For each call that does not have the key and “false” value, we recommend setting up alerts, as the call
most likely was not interpreted. We also recommend logging all calls and the corresponding API response for a 30 days
period.
Every request must have at most 4000 elements. If the call surpasses this limit the call will have a response with key
“isError:true” and “message: Maximum input vars of 4000 exceeded”.
In the event of an documentation error when saving a product, the API will return and “isError:true” message, but the
new offer will be saved and processed.

1.5. Rate limiting

All resources described at the table from paragraph 1.2 have the following limits:

 Maximum 1 request every 3 seconds and maximum 20 requests every 1 minute. For optimal performance we
recommend not scheduling requests at fixed hours. For example use 12:04:42 as a starting point instead of
12:00:00. The following responses are possible:

Time throttling limit is exceeded Time throttling limit was not reached

HTTP/1.1 429 HTTP/1.1 200

Date: Wed, 21 Mar 2018 08:22:44 GMT Date: Wed, 21 Mar 2018 08:23:52 GMT
Content-Type: application/json; charset=utf-8 Content-Type: application/json
Transfer-Encoding: chunked Transfer-Encoding: chunked
X-RateLimit-Limit-3second: 1 X-RateLimit-Limit-3second: 1
X-RateLimit-Remaining-3second: 0 X-RateLimit-Remaining-3second: 0
Server: kong/0.12.1 Server: nginx
{"message":"API rate limit exceeded"} {"isError":false,"messages":[],"results":[]}

Invalid requests will also be limited to a maximum number of 3 requests every 1 minute or 180 requests every 1 hour.

 For API resources that accept bulk save, the limit is 50 entities per request. For optimal performance we
recommend using between 10 and 50 entities per request.

1.6. Callback URLs

The following callback URLs can be activated from the Marketplace interface:

Context Description

New order You will be notified for each new order

Order cancellation You will be notified whenever an order in canceled

New return & status change You will be notified for each new return request and select status changes (New, Acknowledged & Received)

AWB status change You will be notified for each AWB status change

Approved documentation You will be notified when the product documentation is validated and received a PNK

8
 2. Publishing products and offers

We define a draft product as a minimum set of details required to publish a product. The elements are:
 Name
 Brand
 Part number
 Category (optional)
 EAN (optional)
 Source language (optional)

We define a product as a list of elements displayed for a product page. The elements are:
 Name
 Brand
 Part number
 Description
 Images
 Product characteristics (and product families)
 Category
 Barcodes (optional)
 Other attachments (optional)
 EAN (required depending on Category)
 Source language (optional)

We define an offer as a list of elements required for an offer to be available for a product. These elements are:
 Price
 VAT rate
 Warranty
 Numerical stock
 Handling_time

eMAG Marketplace API allows a seller to:

 Send new products and offers
 Send new offers for existing eMAG products (sold by eMAG or any other seller)
 Update existing own offers and/or products

1.7. Reading categories, characteristics and family_types

Every eMAG product has to be included in a certain category. Sellers cannot create new categories or change existing
ones. Also, a seller can only post products and offers in its allowed categories list.

Reading categories without parameters will generate a response containing the first 100 categories. The read can be
paginated thus obtaining a full list of categories. Only active categories will be returned.

9
When passing a category id, the API will return the category name and the list of available characteristics and their
corresponding IDs, as well as the available product family_types and their corresponding IDs. Reading categories one by
one is important as it is the only way to identify the restrictive characteristics and corresponding allowed values.

You can read the categories and their characteristics through the API.

The resource is category and the available actions are read and count.

CATEGORY – read

Key – level 1 Key – level 2 Key – level 3 Description Type Example

id Category eMAG id Integer id=604

name Category name String name=”Music”

is_allowed Indicates if the seller can send Integer is_allowed=0

products and offers in the
category. In order to request
access to a specific category,
you can use the Marketplace
interface.
0 = No 1 = Yes.

parent_id Id of the parent category Integer parent = 12

is_ean_mandatory Indicates if the sending an EAN Integer is_ean_mandatory =1

is mandatory when saving
products
 1 = mandatory
 0 = optional

is_warranty_mandatory Indicates if adding warranty is Integer is_warranty_mandat

mandatory when saving ory =1
products
 1 = mandatory
 0 = optional

characteristics All characteristics available in List of

category arrays

id Characteristic eMAG id Integer id=38

name Characteristic name String name=”Audio”

type_id Characteristic type. Indicates Integer type_id=11

the type of values that a
characteristic can accept.

Single value characteristics:

 1 = Numeric (ex: 20, 1, 30, 40,
etc)
 60 = Size (ex. 36 EU, XL INTL,
etc)
 20 = Boolean ( Yes, No, N/A)

Multiple values
characteristics:

10
 2 = Numeric + unit of
measure ( ex. 30 cm, 45 m, 20
GB, 30 inch, etc)
 11 = Text Fixed (max length
255 chars) (ex. Blue, Green,
Laptop, Notebook, Copil,
Man, Woman)
 30 = Resolution ( Width x
Height ) (ex. 100 x 200, 640 x
480)
 40 = Volume (Width x Height
x Depth - Depth 2) (ex. 30 x
40 x 50 - 10)

display_order Characteristic display order Integer display_order=6

is_mandatory Indicates if the characteristic is Integer is_mandatory=0

mandatory when sending a
product. Possible values are 0
(the characteristic is not
mandatory) and 1 (the
characteristic mandatory).

is_filter Indicates if the characteristic Integer is_filter=1

represents a filter in the
website. Possible values are 0
(the characteristic is not filter)
and 1 (the characteristic is a
filter).

allow_new_value Indicates if the current Integer allow_new_value=0

characteristic allows you to
submit new values that are
automatically validated.

values List the first 256 existing values Array 0 => 'Value 1'
of the current characteristic. 1 => 'Value 2'
Important: This key is available
only when reading a single
category.

tags List of all characteristic tags Array "tags": [

"original",
Important: In the following "converted"
months, characteristic tags will ]
be mandatory.
Characteristic "Converted Size"
(id 10770) will be removed and
its value should be sent on
characteristic "Size" (id 6506) -
"converted" tag:

1. {"id":6506,
o "tag":"original",
o "value":"36 EU"},
2. {"id":6506,
o "tag":"converted",
o "value":"39 intl"}

11
 family_types List of all family types available List of
in category arrays

id Family type id Integer Id=95

name Family name String name=”Quantity”

characteristics All characteristics of current List of

family type arrays

characteristic_id Characteristic Id Integer characteristic_id=44

characteristic_famil Can only have 3 values, each Integer characteristic_family

y_type_id corresponding to a different _type_id=2
display method:
“1" ="Thumbnails";
"2"="Combobox";
"3"="Graphic Selection"

is_foldable A foldable characteristic wraps Integer Is_foldable=1

all family members (with
different characteristic values)
as one item in the eMAG
category listing

display_order Characteristic display order Integer

By default responses will contain category names in the platform language but you can also send the language as a
parameter, in case you want to receive category names in a specifc language. Available languages are: EN, RO, HU, BG,
PL, GR and DE

E.g. https://marketplace-api.emag.ro/api-3/category/read?language=en

1.8. Reading VAT rates

When sending an offer, you have to send the VAT rate id by sending us a valid VAT id.
The resource is vat and the action is read. The API will return the list of available VAT rates and their corresponding id’s.

1.9. Reading Handling Time values

When sending an offer, you have to send the Handling Time by sending us a valid value.
The resource is handling_time and the action is read. The API will return the list of available handling_time values.

1.10. Sending a new product

1.10.1. Draft product

Sending a draft product requires you to send a smaller set of data for publishing a new product. The information is saved
in eMAG platform and the necessary details for publishing a product can be added at any time.

Please note:

12
Draft products won’t be sent to eMAG Catalogue team for validation unless you send the other details necessary for
publishing a new product (described below).

If an EAN published on a draft product is found in the eMAG catalogue you can skip the product publishing process and
attach the offer directly to existing product.

Details for sending a new draft can be found here.

1.10.2. Product

Sending a product for the first time requires you to send the entire product documentation and all the offer data. Please
note that creating new products implies human validation, so a new product will not be displayed in eMAG platform
immediately.
The products that are not compliant with eMAG Documentation Standard will not pass the human validation; in this
case you will be notified by our support team. The eMAG Documentation Standard that is available upon request for
each category, and it contains the best practices for documenting a product.
Important: Content updates will be allowed only on products on which you are eligible (ownership = 1). For products on
which you are not eligible (ownership = 2), any content updates will be rejected.

In order to send a new product, the resource is product_offer and the available action is save.

PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

id Seller internal product id. This Required. Integer value id=243409

is the primary key for between 1 and 16777215.
identifying a product offer.

category_id Product category eMAG id. Required. Integer between 1 category _id=506
and 65535.

vendor_category_id Seller internal category id. Integer. Optional. vendor_category_id=506

part_number_key eMAG part_number_key. Optional. String. Will be part_number_key=ES0NKB

Used for attaching a product validated. BBM
offer to an existing product in
eMAG platform. If you want
to create new product, don’t
set this key.

source_language The language of the product Optional. String. source_language=”de_DE”

content input. Default value:
If it differs from the platform on Marketplace RO: “ro_RO”
local language, then the on Marketplace BG: “bg_BG”
product will enter a on Marketplace HU:
translation process. “hu_HU”
Available values for this key
are: en_GB, ro_RO, pl_PL,
bg_BG, hu_HU, de_DE, it_IT,
fr_FR, es_ES, nl_NL, cs_CZ,
ru_RU, el_GR, lt_LT, sk_SK,
uk_UA

13
PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

name Product name. Should be Required. String between 1 name=”Test product”

consistent with eMAG and 255 characters long.
Product Documentation
Standard.

part_number Manufacturer unique Required. String between 1 part_number=”md788hc/

identifier of the product. and 25 characters. a”
Important:
The following characters will
be automatically stripped:
 spaces [ ]
 comma [ , ]
 semicolon [ ; ]
Example: “part number;” will
be saved “partnumber”

description Product description. Should Optional. String between 1 description=”test”

be consistent with eMAG and 16777215 characters. Can
Product Documentation contain basic HTML tags.
Standard.

brand Brand name. Should be Required. String between 1 brand=”Brand test”

consistent with eMAG and 255 characters.
Product Documentation
Standard.

weight The weight of the product Optional. Decimal value weight=12.123456

between 0 and 999999. Up to
six decimals.

force_images_downloa Image attachement Optional. Integer value, 1 or force_images_download=1

d redownload flag. Only to be 0. Default = 0
used when updating product
documentation
1-forces images redownload
0-images will not be
redownloaded

images Product images data array. Optional. List of arrays.

display_type Image display type. Optional. Default value 0. display_type=1

1 – main image Integer value between 0 and
2 – secondary image 2.
0 – other images

url Seller image URL. Should be Required. String between 1 url=”http://valid-url.jpg”

consistent with eMAG and 1024 characters. Valid
Product Documentation URL. JPG, JPEG or PNG file
Standard. Max 6000px x type.
6000px and 8 Mb in size.

characteristics Characteristic data. Note that Optional. List of arrays.

characteristics have to be
category valid (be part of
category template). Should be
consistent with eMAG

14
PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

Product Documentation
Standard.

id Characteristic eMAG id. Required. Integer value id=24

between 1 and 65535

value Characteristic value. Should Required. String between 1 value=”test”

be consistent with eMAG and 255 characters
Product Documentation
Standard.

tag Characteristic tag value. Required only for tag=”converted”

Should be consistent with characteristics which have
eMAG Product tags on them. String between
Documentation Standard. 1 and 255 characters.

If a characteristic has tags on

the category read route, you
need to send the same
characteristic multiple times
with different value for each
tag.

3. {"id":6506,
o "tag":"original",
o "value":"36 EU"},
4. {"id":6506,
o "tag":"converted",
o "value":"39 intl"}

family Family array. Used to create a Optional. Array.

new family, add a product to
an existing family, or
removing a product from a
family.

id The unique integer identifier Required. Integer Id=0

of the family in your platform.
If set to 0 (id=0), the product
will be removed from its
current family.

name Required. Seller Family name. Required if family id is not name="Test product"
equal to 0;

family_type_i Required. eMAG Family type Required if family id is not family_type_id=95

d id that can be acquired by API equal to 0. Integer.
(the resource is category and
the action is read).

url Product URL on the seller Optional. String between 1 url=”http://valid-url.html”

website. and 1024 characters.

15
PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

warranty The warranty offered in Required/Optional based on warranty=24

months. category.
Default value:
- 0 (no warranty) if optional
- No default if required.
Integer between 0 and 255.

ean Product barcode identifier Required/Optional based on ean=Array('ean1', 'ean2')

(EAN -8, EAN-13, UPC-A, UPC- category. No default value.
E, JAN, ISBN-10, ISBN-13, Array of strings between 6
ISSN, ISMN-10, ISMN-13, and 14 characters long. Only
GTIN-14). Please use the numeric figures allowed.
supplier barcode, not your
internal barcodes.

attachments Product attachments data. Optional. List of arrays.

Max 10 Mb in size.

id Seller attachment internal id. Optional. Integer value id=123

between 1 and 4294967295.

url Seller attachment URL. Required. String between 1 url=”http://valid-url”

and 1024 characters. Valid
URL to document.

status Seller offer status. Required. Integer value, 0, 1, status=1

2 – End of life 2.
1 – status active Obs. status=2 should be used
0 – status inactive only for update

sale_price Seller offer sale price without Required. Decimal value sale_price=51.6477
VAT greater than 0. Up to four
decimals.

recommended_price Seller offer recommended Optional. Decimal value recommended_price=51.64

retail price before discount, greater than 0. Up to four 77
without VAT. If set, the offer decimals. Must be greater
will be displayed as promo. than sale_price.

min_sale_price Seller’s min offer sale price Required on first product min_sale_price=40.6477
without VAT save. Decimal value greater
than 0. Up to four decimals.

max_sale_price Seller’s max offer sale price Required on first product max_sale_price=60.6477
without VAT save. Decimal value greater
than 0. Up to four decimals.
Must be greater than
min_sale_price.

currency_type Offer currency. Only send the Optional. 3 characters string. currency_type=”EUR”
key if it is different from the
local Marketplace currency.
Available options: EUR or PLN

16
PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

stock Offer available quantity array. Required. List of arrays. {

0=>{
warehouse_id=1,
value=20}}

warehouse_id The id of the warehouse. Required inside stock array. warehouse_id=1

Use warehouse_id=1 for only Integer.
one warehouse.

value Offer available quantity. Required inside stock array. value=20

Integer between 0 and 65535.

handling_time Handling time array. If no Optional. List of arrays. {

array is sent, the products are 0=>{
shipped the same day they warehouse_id=1,
are received. value=1}}

warehouse_id The id of the warehouse. Required inside warehouse_id=1

Use warehouse_id=1 for only handling_time array. Integer.
one warehouse.

value Handling time, in number of Required inside value=0

days counted from the day handling_time array. Integer
the order was received. If value between 0 and 255.
handling_time = 0 the order Default value = 0.
will be shipped the same day
it is received.

supply_lead_time The number of days needed Optional. Integer. supply_lead_time=5

to restock the product, from Default value = 14
order placement to the
supplier or production order,
until product reception in the
warehouse.
Available values for this key
are: 2, 3, 5, 7, 14, 30, 60, 90,
120

start_date If it's a new offer, it Optional. Text in YYYY-MM- start_date=”2014-12-31”

represents the date your offer DD format. Date can be as far
will be available from. For as 60 days in the future
offer updates, it schedules (cannot be earlier than
value updates for the tomorrow). Cannot be null.
following data:
 sale_price
 recommended_price
 stock
 handling_time
 vat_id
 warranty
 status
All other data will be updated
on the fly. Using start_date,
for example, you can
schedule the inactivation of
an offer, a price update, etc.

17
 PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

vat_id Seller offer VAT rate id. Required. Integer. Ex: vat _id=1
Use /vat/read to display
possible values.

emag_club Indicates if you want your Optional. Integer value, 1 or emag_club=1

offer to be available or not in 0. Default = 1
the eMAG Genius program.
Only eligible offers will display
Genius benefits to customers
eMAG website even if you
have chosen them to be
available.

IMPORTANT:

 During campaings with stock in site we will not allow the following:
o regular offer updates;
o updates sent during campaign time that have a start_date in the future;
o previously scheduled updates with start_date during campaign time.
 You can save an offer update with currency_type different from the local Marketplace currency and start_date
before the end of the current month. Any update attempt with a start_date greater than the last day of the
current month will be rejected.
 Be aware that prices published directly in the local Marketplace currencies will be overwritten by prices
published in other currencies when these are recalculated and published automatically on FX change at the
beginning of every month. The automated recalculation can be disabled on request.
 Min / Max sale price keys are used for price check purposes and are mandatory for all calls used to create
product/offers for the first time. As a best practice we recommend sending these keys only when you want to
change their values.
 Sale price will be validated against min_sale_price and max_sale_price. Any offer that is not within the specified
range will be rejected.
 In order to change a previously sent product image or attachment the url should be different from the one
already sent. We reload the images only if the URL differs.
 We recommend sending the product data only upon product create/update, as there is no need to resend
product unless it changed. Also we recommend sending the offer data upon changing (no matter the frequency)
and at least weekly (even if the offer is the same) rather using periodical sending (crons, agents). You should
program marketing campaigns using “start_date” campaign. Also please offer the possibility for an offer to be
attached to an existing eMAG product (using part_number_key).
 The product part number should be assigned to a single product.
If a product part number is re-used (set on a second product) an error will be generated and the product will
NOT be saved.
 Multiple EAN codes can be set on an offer, but one EAN product code can NOT be used on two or more
products.
If one EAN code is added on a second new product, an error will be generated and the product will NOT be
saved.

18
 If one EAN code used on a new product is already linked to a product in the eMAG catalogue, the offer will be
automatically associated to that existing product.
 In the event of an documentation error when saving a product, the API will return and “isError:true” message,
but the new offer will be saved and processed.
 When adding a product to a family
o The category id of a product and the category id of its family type (family_type_id) must be the same.
o All characteristics that define a family must be present and must have a valid value
o All characteristics that define a family must have a single value
o If a family is not valid, you will receive a warning response, but the product will be saved/updated
o When moving a product from one family to another you only have to send the product with its new
family type, id and name and make sure you follow the same rules as above

1.11. Example for a new product

Resource Example Context

http method: POST

product_offer/save

1.12. Updating existing offer

When updating an existing offer for a product, you should send only the offer, without the documentation. Mandatory
when updating a product offer are the following keys:
 id
 status
 sale_price
 vat_id
 handling_time
 stock

Please note that although the API permits sending the entire documentation on each offer update (price change, out-of-
stock change, etc.) we do not recommend or encourage such a practice.

If you need to deactivate a valid offer on the website, you should send the offer with the “status = 0”.

1.13. Saving volume measurements on products

In order to save volume measurements on existing products, the resource is measurements and the available action is
save. The measurement units for volume are millimeters and grams.

MEASUREMENTS – save

Key – level 1 Description Constraints Example

id Seller internal product id. This is the Required. Integer value between 1 and id=243409
primary key for identifying a product 16777215.
offer.

19
 MEASUREMENTS – save

Key – level 1 Description Constraints Example

length The length of the product in millimeters Required. Decimal value between 0 and 999999. length=100
(mm) Up to two decimals.

width The width of the product in millimeters Required. Decimal value between 0 and 999999. width=122.50
(mm) Up to two decimals.

height The height of the product in millimeters Required. Decimal value between 0 and 999999. height=250
(mm) Up to two decimals.

weight The weight of the product in grams (g) Required. Decimal value between 0 and 999999. weight=1254.50
Up to two decimals.

Resource Example Context

http method: POST

measurements/save

1.14. Reading and counting products and offers

In order to check the existing products (offers) and their status, the resource is product_offer and the available action
are read and count.

Important: When reading products, only your own content input on the product will be returned.

PRODUCT_OFFER – read

Key – level 1 Key – level 2 Description Type Example

part_number_key eMAG part_number_key. String part_number_key=ES0

NKBBBM

number_of_offers How many sellers have active offers on this product Integer number_of_offers=3

buy_button_rank The rank of the offer in its race to win the <Add to cart> Integer buy_button_rank=1
button

best_offer_sale_price Best selling price available in eMAG for the same Product Decimal best_offer_sale_price=
51.6477

best_offer_recommend The corresponding recommended price for the offer Decimal best_offer_recommen
ed_price holding the best selling price ded_price=54.6477

ownership Indicates who has ownership on the product’s Integer ownership=1

documentation. Posible values:
1 – Eligible for content updates
2 – Not eligible for content updates

category_id Product category eMAG id. Integer category _id=506

20
 PRODUCT_OFFER – read

Key – level 1 Key – level 2 Description Type Example

vendor_category_id Seller internal category id. Integer vendor_category_id=5

06

id Seller internal product id. This is the primary key for Integer id=243409
identifying a product offer.

brand Product brand name. String brand=”Brand test”

name Product name. String name=”Test product”

part_number Product part number. String part_number=”md788

hc/a”

sale_price Seller offer sale price without VAT Decimal sale_price=51.6477

recommended_price Seller offer recommended retail price before discount, Decimal recommended_price=
without VAT. 54.6477

currency Product price currency. String currency='RON'

description Product description. String description=”test”

url Product URL on the seller website. String url=”http://valid-

url.html”

warranty The warranty offered in months. Integer warranty=24

ean Product barcode identifier (EAN -8, EAN-13, UPC-A, UPC- Array ean=Array('ean1',
E, JAN, ISBN-10, ISBN-13, ISSN, ISMN-10, ISMN-13, GTIN- 'ean2')
14).

general_stock The sum of the stock on all seller warehouses. Is Integer general_stock=20
decremented and incremented when orders are
processed.

estimated_stock This key takes into account the reserved stock on Integer estimated_stock=20
unacknowledged orders.

weight The weight of the product Decimal weight=12.123456

status Seller offer status. Integer status=1

2 – end of life
1 – status active
0 – status inactive

images List of
arrays

url Seller image URL. String url=”http://valid-

url.jpg”

display_type Image display type. Integer display_type=1

1 – main image
2 – secondary image
0 – other images

21
 PRODUCT_OFFER – read

Key – level 1 Key – level 2 Description Type Example

characteristics All characteristics available in category List of

arrays

id Characteristic eMAG id Integer id=38

value Characteristic value. String value=”test”

vat_id Seller offer VAT rate id. Integer vat _id=1

family Product family. Array

id Family id. Integer id=295

name Family name. String name=”Test family”

handling_time List of
arrays

warehouse_i The id of the warehouse. Integer warehouse_id=1

d

value Handling time, in number of days counted from the day Integer value=0
the order was received.

validation_status Product validation status List of

arrays

value Product validation status value Integer value=4

Description Product validation status description String Description=”Rejected

documentation”

offer_validation_status Offer validation status List of

arrays

value Offer validation status value Integer value=2

Description Offer validation status description String Description=”Invalid

price”

genius_eligibility Indicates if the offer is eligible for Genius program. Integer value=1

The following filters are available when counting and reading products and offers:

Key Description Constraints

id Displays the details for the Optional. Integer value between 1 and 4294967295.
corresponding ext_id.

currentPage Set current page displayed Optional, integer.

Ex: currentPage =3

22
 Key Description Constraints

itemsPerPage Set number of items to be displayed in Optional, integer.

one page. Maximum is set to 100. itemsPerPage=50

status Returns only the offers with this status. Optional. Seller offer status.
1 – status active
0 – status inactive

general_stock Returns only offers with numerical Optional

general_stock that have a value general_stock = 3
between 0 and the input.

estimated_stock Returns only offers with numerical Optional

estimated_stock that have a value reserved_stock = 3
between 0 and the input.

offer_validation_status Returns only the results with this Optional.

validation status. 1 = Saleable
2 = Invalid price

validation_status Returns only the results with this Optional.

validation status. 1 = Awaiting MKTP validation
2 = Awaiting Brand validation
3 = Awaiting EAN validation
4 = Awaiting Documentation Validation
5 = Rejected Brand
6 = Rejected EAN
7 = Rejected Association
8 = Rejected Documentation
9 = Approved Documentation
10 = Blocked
11 = Documentation update validation pending
12 = Update rejected

translation_validation_status Returns only the results with this Optional.

validation status. 1 = Awaiting MKTP validation
2 = Awaiting Brand validation
3 = Awaiting EAN validation
4 = Awaiting Documentation Validation
5 = Rejected Brand
6 = Rejected EAN
7 = Rejected Association
8 = Rejected Documentation
9 = Approved Documentation
10 = Blocked
11 = Documentation update validation pending
12 = Update rejected
13 = Waiting for salable offer
14 = Unsuccessful translation
15 = Translation in progress
16 = Translation pending
17 = Partial translation

Reading products will always return the values sent by sellers.

In order to be available for selling, an offer has to meet the following conditions:

 Stock > 0
23
  Seller status should be active
 All 3 keys (“status”,”offer_validation_status”, “validation_status”) should have values that allows availability, see
details below:

Key Status Availability Description

“status”:0 Inactive/Auto-inactivated Not allowed The status can be set by the seller on the offers
temporary unavailable. The status can be also
set based on losing access in the category,
losing an EAN conflict, etc
“status”:1 Active Allowed The status is set by the seller when they want
to sell the offer.
“status”:2 EOL/ Auto EOL Not allowed The status that can be set by the seller on the
offers that does not want to sell them
anymore. The status can be also set based on
the Auto EOL flow.
“offer_validation_status”-> Valid Allowed Feedback based on price check. If the value =1,
”value”:1 means that price is valid and the offer can be
sell.
“offer_validation_status”:-> Invalid price Not allowed Feedback based on price check. If the value =2,
“value”:2 means that price is not valid and the offer
cannot be sell until the price is manually
validated.
“validation_status”:-> “value”:1 In MKTP validation Not allowed This value is applied on new products that
needs MKTP validation in order to be sent to
eMAG systems.
“validation_status”:-> “value”:3 Waiting for EAN approval Allowed This value signals the presence of an EAN
conflict, but does not influence the availability
of an offer until it is resolved.
“validation_status”:-> “value”:4 New documentation validation Not allowed Newly documented product that has not been
pending finalized/validated.
“validation_status”:-> “value”:6 Invalid product – EAN rejected Not allowed The product has lost an EAN conflict and the
offer has been inactivated (“status”:0)
“validation_status”:-> “value”:8 Documentation rejected Not allowed Newly documented product that does not
meet the criteria and requires correction to the
documentation.
“validation_status”:-> “value”:9 Approved documentation Allowed The product is documented, approved and can
be sold if it has a saleable offer attached. For
this status, there may be exceptions in the case
of automatically translated products, as they
are not published on the site even though they
have this status. Please check
“translation_validation_status” key which
allows a greater granularity to identify the
translated products.
“validation_status”:-> “value”:10 Blocked Not allowed The offer for these products has been blocked
from sale by an admin or an automatic flow,
such as Product health or OPC. In order to be
unblocked, It requires the validation by an
admin.
“validation_status”:-> “value”:11 Update awaiting approval Allowed Documented and approved product that can
be sold, but for which the validation of some
updates sent by the seller is pending. For this
status, there may be exceptions in the case of
automatically translated products, as they are
not published on the site even though they

24
Key Status Availability Description
have this status. Please check
“translation_validation_status” key which
allows a greater granularity to identify the
translated products.
“validation_status”:-> “value”:12 Update rejected Allowed Documented and approved product that can
be sold, but for which the validation of some
updates sent by the seller were rejected.
“translation_validation_status”:-> In MKTP validation Not allowed This value is applied on new products that
“value”:1 needs MKTP validation in order to be sent to
eMAG systems.
“translation_validation_status”:-> Waiting for EAN approval Allowed This value signals the presence of an EAN
“value”:3 conflict, but does not influence the availability
of an offer until it is resolved.
“translation_validation_status”:-> New documentation validation Not allowed Newly documented product that has not been
“value”:4 pending finalized/validated.
“translation_validation_status”:-> Invalid product – EAN rejected Not allowed The product has lost an EAN conflict and the
“value”:6 offer has been inactivated (“status”:0)
“translation_validation_status”:-> Documentation rejected Not allowed Newly documented product that does not
“value”:8 meet the criteria and requires correction to the
documentation.
“translation_validation_status”:-> Approved documentation Allowed The product is documented, approved and can
“value”:9 be sold if it has a saleable offer attached.
“translation_validation_status”:-> Blocked Not allowed The offer for these products has been blocked
“value”:10 from sale by an admin or an automatic flow,
such as Product health or OPC. In order to be
unblocked, It requires the validation by an
admin.
“translation_validation_status”:-> Update awaiting approval Allowed Documented and approved product that can
“value”:11 be sold, but for which the validation of some
updates sent by the seller is pending.
“translation_validation_status”:-> Update rejected Allowed Documented and approved product that can
“value”:12 be sold, but for which the validation of some
updates sent by the seller were rejected.
“translation_validation_status”:-> Waiting for salable offer Not allowed In order for the translation to be prioritized,
“value”:13 make sure that the offer has stock and is active
“translation_validation_status”:-> Unsuccessful translation Not allowed Translation request for new product that does
“value”:14 not meet the criteria and requires correction to
the documentation.
“translation_validation_status”:-> Translation in progress Not allowed Automatic translated product, with PNK, not
“value”:15 yet displayed on customer website, which is
now in the process of manual translation
“translation_validation_status”:-> Translation pending Not allowed New product translation request which waits
“value”:16 processing
“translation_validation_status”:-> Partial translation Allowed Automatic translated product with PNK,
“value”:17 already published to cutomer website

1.15. Product validation responses

After reading a product, all the elements previously sent are returned, along with the key doc_errors. The key is not null
for products that were rejected due to improper documentation. Below the list of possible errors, when they occur and
the possible actions you need to take.

25
 1.16. Attaching offers on existing products

The attaching action can be done via product_offer/save route.

You can choose between using PNK (part_number_key) or EAN for attaching offers on existing eMAG products.

If the product already exists in eMAG catalog, just add the key “part_number_key” with product’s part_number_key or
the “ean” key with a single EAN.

IMPORTANT:

Only one offer can be attached to an existing product (identified by a “part_number_key”) in eMAG catalogue.
In case you try to attach a second offer to a “part_number_key” that already has one of your offers attached, an error
will be generated and the offer will NOT be saved.
If you already have an offer attached to a “part_number_key” please update it instead of trying to attach a new one.

The part_number_key is the last key found in the URL of an eMAG product. It will ALWAYS have both numbers
and characters. Ex: for product http://www.emag.ro/telefon-mobil-nokia-105-black-105-black/pd/D5DD9BBBM/
the part_number_key is D5DD9BBBM.

PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

id Seller internal product id. Required. Integer value id=243409

This is the primary key for between 1 and 16777215.
identifying a product offer.

name Product name. Should be Required. String between 1 name=”Test product”

consistent with eMAG and 255 characters long.
Product Documentation
Standard.

ean Product barcode identifier Required if part_number_key ean=Array('ean1')

(EAN -8, EAN-13, UPC-A, is not present. No default
UPC-E, JAN, ISBN-10, ISBN- value. Array of strings
13, ISSN, ISMN-10, ISMN-13, between 6 and 14 characters
GTIN-14). Please use the long. Only numeric figures
supplier barcode, not your allowed.
internal barcodes. OBS: “part_number_key” and
“ean” keys are mutually
exclusive, you should use one
or the other.

26
PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

part_number_key eMAG part_number_key. Required if ean is not present. part_number_key=ES0NK

Used for attaching a product String. Will be validated BBBM
offer to an existing product OBS: “part_number_key” and
in eMAG platform. If you “ean” keys are mutually
want to create new product, exclusive, you should use one
don’t set this key. or the other.

status Seller offer status. Required. Integer value, 1 or status=1

1 – status active 0.
0 – status inactive

sale_price Seller offer sale price Required. Decimal value sale_price=51.6477

without VAT greater than 0. Up to four
decimals.

recommended_price Seller offer recommended Optional. Decimal value recommended_price=51.6

retail price before discount, greater than 0. Up to four 477
without VAT. If set, the offer decimals. Must be greater
will be displayed as promo. than sale_price.

min_sale_price Seller’s min offer sale price Required on first product min_sale_price=40.6477
without VAT save. Decimal value greater
than 0. Up to four decimals.

max_sale_price Seller’s max offer sale price Required on first product max_sale_price=60.6477
without VAT save. Decimal value greater
than 0. Up to four decimals.
Must be greater than
min_sale_price.

currency_type Offer currency. Only send Optional. 3 characters string. currency_type=”EUR”

the key if it is different from
the local Marketplace
currency. Available options:
EUR or PLN

vat_id Seller offer VAT rate id. Required. Integer. Ex: vat _id=1
Use /vat/read to display
possible values.

stock Offer available quantity Required. List of arrays. {

array. 0=>{
warehouse_id=1,
value=20}}

stock warehouse_id The id of the warehouse. Required inside stock array. warehouse_id=1
Use warehouse_id=1 for Integer.
only one warehouse.

stock value Offer available quantity. Required inside stock array. value=20
Integer between 0 and 65535.

handling_time Handling time array. If no Optional. List of arrays. {

array is sent, the products 0=>{
are shipped the same day warehouse_id=1,
they are received. value=1}}

27
 PRODUCT OFFER – save and create/update product

Key – level 1 Key – level 2 Description Constraints Example

handling_time warehouse_id The id of the warehouse. Required inside warehouse_id=1

Use warehouse_id=1 for handling_time array. Integer.
only one warehouse.

handling_time value Handling time, in number of Required inside value=0

days counted from the day handling_time array. Integer
the order was received. If value between 0 and 255.
handling_time = 0 the order Default value = 0.
will be shipped the same day
it is received.

start_date If it's a new offer, it Optional. Text in YYYY-MM- start_date=”2014-12-31”

represents the date your DD format. Date can be as far
offer will be available from. as 60 days in the future
For offer updates, it (cannot be earlier than
schedules value updates for tomorrow). Cannot be null.
the following data:
 sale_price
 recommended_price
 stock
 handling_time
 vat_id
 warranty
 status
All other data will be
updated on the fly. Using
start_date, for example, you
can schedule the
inactivation of an offer, a
price update, etc.

warranty The warranty offered in Required/Optional based on warranty=24

months. category.
Default value:
- 0 (no warranty) if optional
- No default if required.
Integer between 0 and 255.

Resource Example Context

http method: POST

product_offer/save

1.17. Reading commission for an offer

In order to read the estimated commission for an offer, a new REST API is available. Please consult the API Swagger.

3. Updating stock
In order to update only the stock of an offer a REST resource is available
28
 Resource Resource URL Method Authorization Headers Parameters

offer_stock MARKETPLACE_API_URL/offer_stock/{resourceId} PATCH Basic (Base64) Content-Type application/json resourceId

The resourceId parameter represents the Seller internal product id. This is the primary key for identifying a product
offer.

Resource Example Context

http method: PATCH

offer_stock

4. Proposing offers in campaigns

To propose a valid offer in a campaign the resource is campaign_proposals and the available action is save.

Proposing offers in campaigns

Key – level 1 Key – level 2 Description Constraints Example

id Seller internal product id. Required. Integer value id=243409

This is the primary key for between 1 and 16777215.
identifying a product offer.

sale_price Seller offer sale price Required. Decimal value sale_price=51.6477

without VAT available in the greater than 0. Up to four
campaign decimals.

original_sale_price Seller offer recommended Optional. Decimal value original_sale_price

retail price before discount, greater than 0. Up to four =51.6477
without VAT available in the decimals. Must be greater
campaign. If set, the offer than sale_price.
will be displayed as promo.

stock Available stock for the Required. Integer value stock=1

campaign. Once the stock between 0 and 255.
has finished, the product can
no longer be ordered.

max_qty_per_order The maximum quantity that Required/Optional depending max_qty_per_order=4

a customer can order for a on campaign type. List of
product from the campaign. arrays.
This column is mandatory
for stock in site campaigns.

post_campaign_sale_pri Product price after campaign Optional. Decimal. Up to four post_campaign_sale_pric

ce end. The automatically filled decimals. e=55.6477
price is the sale price of the
product from the moment
when offers are
downloaded.

29
 Proposing offers in campaigns

Key – level 1 Key – level 2 Description Constraints Example

post_campaign_original_ Recommended retail price Optional. Decimal. Up to four post_campaign_original_s

sale_price before discount of the decimals. ale_price=60.6477
product, available after
campaign end.

campaign_id eMAG internal campaign ID Required. Integer value campaign_id=344

in which the proposal will be between 1 and 16777215.
uploaded

Resource Example Context

http method: POST

campaign_proposals/save

5. Processing orders
An order consists of customer details, products and discounts from vouchers. It also has information about payment
method, shipping tax. Also, each order always has a status attached. The available statuses are:
0 – canceled
1 – new
2 – in progress
3 – prepared
4 – finalized
5 – returned
The resource is order and the available actions are read, save, count and acknowledge.

1.18. Order fields

An order has the following properties:

Key – level 1 Key – level 2 Description Constraints Example

id The number that uniquely Required. id=939393

identifies an order. Integer value
between 1 and
4294967295.

status The order processing status. Required. status=1

Possible values: Integer value
0 - cancelled between 0 and
1 - new 5.
2 - in progress
3 – prepared
4 - finalized
5 - returned

30
Key – level 1 Key – level 2 Description Constraints Example

is_complete A flag indicating if the order is Optional. Integer is_complete=1

complete (has all details value.
necessary for processing) or not.
Possible values:
0 - incomplete;
1 - complete.

type A flag indicating if the order Optional. Integer type=3

contains products fulfilled by value.
eMAG or by seller. Possible
values:
2 – fulfilled by eMAG
3 – fulfilled by seller

payment_mode_id The order payment method. Required. payment_mode_id=1

Possible values: Integer.
1 - COD (cash on delivery)
2 - bank transfer
3 - online card payment

detailed_payment_method The detailed order payment Optional. String. detailed_payment_method

method. = “eCREDIT”

delivery_mode The order delivery method. Optional. String. delivery_mode=”courier”

Possible values:
“courier” – home delivery
“pickup” – locker delivery

details Order extra details. Optional. Array.

details locker_id The pickup point id, if the locker Optional. String. locker_id=”dce0b7cf-dc38-
delivery option was selected by a 11e8-a7d8-001a4a160153”
customer.

locker_name The pickup point name, if the Optional. String. locker_name=”easybox

locker delivery option was eMAG Showroom”
selected by a customer.

locker_delivery_eligible Indicates if the order, regardless Optional. Integer locker_delivery_eligible=1

of the delivery method selected value.
by the customer, would fit into a
locker.
0 – not eligible for locker delivery
1 – eligible for locker delivery

date The cart submission timestamp. Optional. Text in date=”1970-01-01

YYYY-mm-dd 23:59:59”
HH:ii:ss format.

payment_status The online payment status. Only Required only payment_status=0

used for online payment for online
methods. Possible values: payment
0 - not paid methods.
1 - paid Integer. It is
highly
recommended
to also interpret
the payment

31
Key – level 1 Key – level 2 Description Constraints Example

status when
reading orders
with Card Online
payment
method.

cashed_co The cashed amount from Card Optional.

online payment Integer.

cashed_cod The cashed amount from cash on Optional.

delivery payment Integer.

shipping_tax The shipment tax value. Optional. shipping_tax=”19.99”

Decimal.

shipping_tax_voucher_split A list of arrays describing the List.

voucher discounts distribution on
shipping tax level.

voucher_id The ID of the voucher discount Optional. Integer voucher_id=123

value between 1
and 9999999.

value The value of the discount, Optional. value=-200

whitout VAT Negative value.

vat_value The value of the VAT Optional. Vat_value=-38

Negative value.

customer A list with the details about the Optional. List. The field list is detailed
customer, the shipping and the below.
billing addresses.

products A list of arrays describing the List. The field list is detailed
products in the order. below.

attachments A list of arrays describing the List. The field list is detailed
attachments in the order. below (chapter 3.1.3).

vouchers A list describing the voucher List.

discounts.

vouchers voucher_id The ID of the voucher discount Optional. Integer voucher_id=123

value between 1
and 9999999.

modified The modified date of the voucher Optional. Text in modified="2015-04-23

discount YYYY-mm-dd 11:30:09"
HH:ii:ss format.

created The date of the voucher discount Optional. Text in created="2015-04-23

YYYY-mm-dd 11:30:09"
HH:ii:ss format.

status The status of the voucher Optional. status=1

discount Integer.

sale_price_vat The value of the VAT Optional. sale_price_vat=”-1.9355"

32
Key – level 1 Key – level 2 Description Constraints Example

Negative value.

sale_price The value of the discount, Optional. sale_price="-8.0645"

without VAT Negative value.

voucher_name The name of the voucher Optional. String. voucher_name="eMAG

giftcard"

vat The VAT rate Optional. vat="0.24"

Decimal.

issue_date The date when the voucher was Optional. Text in issue_date="2020-06-09"
issued YYYY-mm-dd
format.

is_storno Mandatory key when products Optional. is_storno=true

are returned for a finalized order. Boolean.
Further details here. True indicates
partial storno.

cancellation_reason The order cancellation reason. Optional. Integer cancellation_reason=1

Possible values: value between 1
and 5.
1 - Out of stock
2 - Cancelled by the client
3 - The client can not be
contacted
15 - Courier delivery term is too
large
16 - Transport tax, is too large
17 - Large delivery term, until the
product will arrive in our
warehouse
18 - Better offer in another store
19 - Payment order has not been
paid
20 - Undelivered order, courier
reasons
21 - Others
22 - Order Incomplete - automatic
cancellation
23 - The customer changed his
mind
24 - By customer request
25 - Failed delivery
26 - Late shipment
27 - Irrelevant Order
28 - Canceled by SuperAdmin on
seller request
29 - Blacklisted customer
30 - No VAT invoice
31 - The eMAG Marketplace
partner requested the order
cancellation
32 - The delivery estimate is too
long
33 - The product is no longer
available in the stock of the

33
Key – level 1 Key – level 2 Description Constraints Example

eMAG Marketplace partner

34 - Other reasons
35 - The delivery is too expensive
36 - The customer found a better
price elsewhere
37 - The customer registered
another eMAG order with a
similar product
38 - The customer changed his
mind, does not need the product
39 - The customer can purchase
the product only by installments

1.18.1. Product field in order details

Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

id eMAG internal Required. Integer id=123

order product value between 1 and
line id. Any 9999999. id=243409
update on order
product lines
must use this id.

product_id Seller internal Optional. Integer. product_id=3331

product id. This
is the primary
key for
identifying a
product offer.

product_voucher_split A list of arrays List.

describing the
voucher
discounts
distribution on
product level.

voucher_id The ID of the Optional. Integer voucher_id=123

voucher value between 1 and
discount 9999999.

value The value of the Optional. Negative value=-200

discount, value.
whitout VAT

vat_value The value of the Optional. Negative Vat_value=-38

VAT value.

status The status of Required. Integer. status=1

product of the
order. Possible
values:
0 - cancelled

34
Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

1 - active

part_number Manufacturer Optional. String part_number='682133frs'

unique identifier between 1 and 25
for the product. characters.
Important:
The following
characters will be
automatically
stripped:
 spaces [ ]
 comma
[,]
 semicolon
[;]
Example: “part
number;” will be
saved “partnumber”

created The date when Optional. Text in created='2014-07-24

the order YYYY-mm-dd HH:ii:ss 12:16:50'
product line was format.
created.

modified The date when Optional. Text in modified='2014-07-24

the order YYYY-mm-dd HH:ii:ss 12:18:53'
product line was format.
last modified.

currency Product price Optional. String. currency='RON'

currency.

quantity Product Required. Integer. quantity=2

quantity. Positive, different
than 0.

sale_price The sale price Required. Integer. sale_price=12.1234

without VAT.

details Additional Optional. Text. details=”text”

product notes.

status The status of Required. Integer. status=1

product of the
order. Possible
values:
0 - cancelled
1 - active

sale_price The sale price Required. Integer. sale_price=12.1234

without VAT.

details Additional Optional. Text. details=”text”

product notes.

recycle_warranties

quantity Warranty Optional. Integer. quantity=6

35
 Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

quantity.

sale_price The sale price Optional. Integer. sale_price=0.5

without VAT.

vat_rate The rate of the Optional. Integer. vat_rate=0

VAT

product_name The name of the Optional. String. product_name=”Taxa

recycle SGR metal”
warranty:
plastic, metal,
glass

recycle_warranty_voucher_split A list of arrays List.

describing the
voucher
discounts
distribution on
recyle warranty
level.

voucher_id The ID of the Optional. Integer voucher_id=875

voucher value between 1 and
discount 9999999.

value The value of the Optional. Negative value=-3

discount, value.
whitout VAT

vat_value The value of the Optional. Negative vat_value=0

VAT value.

IMPORTANT

Please note that multiple vouchers, possibly having different VAT rates, can be applied on a product. You should always
read all voucher parameters.

1.18.2. Customer fields in order details

The customer field has the following properties:

Key Description Constraints Example

id The number that uniquely identifies a customer. Optional. Integer value id=1
between 1 and2147483647.

name The customer's name. Optional. Text. name=”Surname Name”

email This is a hash that uniquely identifies the Optional. Text. email=”[email protected]”
customer’s email.

company The name of the company. For physical person it Optional. Text. company=”Company name
has the same value as name. ltd.”

36
 Key Description Constraints Example

gender The customer gender. Possible values: Optional. Text. gender=”M”

M - male
F – female

code The company registration code. Optional. Text. code=”14399840”

registration_number The company registration number. Optional. Text registration_number=”

40/372/2002”

bank The bank name. Optional. Text. bank=”Bank name”

iban The bank account. Optional. Text. iban=”

RO24BACX0000000031430310”

fax The customer's fax number. Optional. Text. fax=”4021123123”

legal_entity A flag indicating if the customer is physical or Optional. Integer value. legal_entity=1
juridical entity. Possible values:
0 - private entity;
1 - legal entity.

is_vat_payer A flag indicating it the customer is vat payer. Optional. Integer value. is_vat_payer=0
Possible values:
0 - the customer is not vat payer;
1 - the customer is vat payer.

phone_1 The customer's first phone number. Optional. Text. phone_1=”4021123123”

phone_2 The customer's second phone number. Optional. Text.

phone_3 The customer's third phone number. Optional. Text.

billing_name The customer's invoice name. Optional. Text. billing_name=”Surname Name”

billing_phone The customer's invoice phone. Optional. Text. billing_phone=”4021123123”

billing_country The customer's invoice country. Optional. Text. billing_country=”Romania”

billing_suburb The customer's invoice county. Optional. Text. billing_suburb=”Suburb”

billing_city The customer's invoice city. Optional. Text. billing_city=”City”

billing_street The customer's invoice address. Optional. Text. billing_street=”Street Name”

billing_postal_code The customer's invoice postal code. Optional. Text. billing_postal_code=”23125”

shipping_contact The name of the contact person that will pick up Optional. Text. shipping_contact=”Name
the parcel. Should be printed on the AWB. Surname”

shipping_phone The phone used by the courrier to contact the Optional. Text. shipping_phone=”23125”
shipping person. Should be printed on the AWB.

1.18.3. Order invoices

When pushing orders into finalized status, you should also send the invoice PDF file location for the specific order.

37
The resource is order/attachments and the available action is save.

The following keys should be sent in attachments array in order to display an invoice in the customer’s order details:
name, url, type.

An attachment has the following properties:

Key Description Constraints Example

order_id The number that uniquely identifies an order. Required. Integer value id=939393
between 1 and 4294967295.

name The name of the attachment displayed to the customer (in order Optional. String between 1 name='Invoice
history or in email) and 60 characters title'

url Attachment URL. Required. String between 1 url=”http://valid-

and 1024 characters. Valid url/invoice.pdf”
URL to document.

type The type of document attached to the order. Possible values are: Integer. Optional. Default type=1
 1 - invoice 1=”Invoice”. Only .pdf files
 3 - warranty are accepted
 4 - user manual
 8 - user guide
 10 - AWB
 11 - proforma

force_downloa Flag used in order to force attachment download restrictions. If value Integer. Optional. Default force_download=0
d is 0 and the attachment URL has not changed, the attachment will not value 0. Possible values: 0,1.
be downloaded again.

1.19. Order notification, acknowledgment and order filters

When a new order is placed in eMAG Marketplace for the first time, it’s status is 1 (new) and a GET request with the
order id is automatically made to an URL you provide (call-back URL). Ex: http://valid_url/path?order_id=123

In the next step, you should read the order passing the id previously mentioned and after successfully saving the order in
your database you should notify us by calling back the API using the route MARKETPLACE
_URL/api-3/order/acknowledge/[orderId]. This stops the order notification system for the mentioned order. Unless
acknowledged, we will notify the new orders for up to 48 hours.

IMPORTANT:
 Order acknowledge is the only method of marking the order status as “in progress”.
 Clients may ask for an order to be canceled, this will be done by eMAG only if the order was not acknowledged
by the seller, thus some of the orders may be read directly with status 0 (canceled).

1.20. Order status matrix

The following matrix defines the order flow in eMAG Marketplace:

New status
Actual status 1 - New 2 - In progress 3 – Prepared 4 - Finalized 0 - Canceled 5 - Returned
38
 Yes by ACK
1 - New No No No No No
only
2 - In progress No Yes Yes Yes Yes No
3 - Prepared No No Yes Yes Yes No
Yes in 48h
4 - Finalized No No Yes in 48h max Yes Yes in RT* + 5 days max
max
0 - Canceled No Yes in 48h max Yes in 48h max Yes in 48h max Yes No
5 - Returned No No No No No No
*RT = return time allowed to customers

IMPORTANT:
 We recommend setting up a periodical /order/read (cron, agent) that should identify orders that were not
acknowledged. By default on /order/read we expose the last 100 orders, but you can request up to 1000 or use
pagination. Do not forget to test the order status matrix against your internal order workflow. As a best practice
you should either acknowledge the order prior the read or re-read the order after acknowledging it; an order
can be modified by eMAG employees upon the client’s request as long as it is not acknowledged;
 You can only edit the order (add/remove products modify quantity or price) when in status 2 (in progress) or 3
(prepared);
 Once an order is finalized, you can change its status back to status 3 (prepared) or 0 (canceled) only in the first
48 hours since finalization;
 Order status “finalized” will be set automatically when issuing the first AWB for that order. See chapter Saving
AWBs;
 The order status “returned” is set automatically when all the products from the initial invoice are marked as
returned. The change is permitted only within the maximum return timeframe allowed to the customer.

1.21. Order filters

You can read all your orders though the API, using filters. The following are available when counting orders:

Key Description Constraints

id Only the order with this value. Optional. Integer value between 1
and4294967295.

createdBefore Only the orders created before the specified date. Optional. Text in YYYY-mm-dd HH:ii:ss
Can only be set if “createdAfter” is present. Maximum 1 month format.
difference.

createdAfter Only the orders created after the specified date. Can only be set if Optional. Text in YYYY-mm-dd HH:ii:ss
“createdBefore” is present. Maximum 1 month difference. format.

modifiedBefore Only the orders modified before the specified date. Can only be set if Optional. Text in YYYY-mm-dd HH:ii:ss
“modifiedAfter” is present. Maximum 1 month difference. format.

modifiedAfter Only the orders after before the specified date. Can only be set if Optional. Text in YYYY-mm-dd HH:ii:ss
“modifiedBefore” is present. Maximum 1 month difference. format.

status Only the orders with the specified status. It is a single value or a list of Optional. Integer or list.
values.

payment_mode_ id Only the orders with the specified payment method id. It is a single Optional. Integer or list.

39
 Key Description Constraints

value or a list of values.

is_complete Only the orders with the specified completion status. Optional. Order completion status.
1 – complete orders
0 – incomplete orders

type Only the orders with the specified type Optional. Default value = 3.
2 – fulfilled by eMAG
3 – fulfilled by seller

The following filters are available when reading orders:

Key Description Constraints

itemsPerPage The maximum number of orders to return. Optional. Integer value between 1
and 100.

currentPage The page offset. Optional. Integer value between 1

and 65535.

id Only the order with this value. Optional. Integer value between 1
and4294967295.

createdBefore Only the orders created before the specified date. Can only be set if Optional. Text in YYYY-mm-dd
“createdAfter” is present. Maximum 1 month difference. HH:ii:ss format.

createdAfter Only the orders created after the specified date. Optional. Text in YYYY-mm-dd
HH:ii:ss format.

modifiedBefore Only the orders modified before the specified date. Can only be set if Optional. Text in YYYY-mm-dd
“modifiedAfter” is present. Maximum 1 month difference. HH:ii:ss format.

modifiedAfter Only the orders after the specified date. Optional. Text in YYYY-mm-dd
HH:ii:ss format.

status Only the orders with the specified status. It is a single value or a list of values. Optional. Integer or list.

payment_mode_i Only the orders with the specified payment method id. It is a single value or a Optional. Integer or list.
d list of values.

is_complete Only the orders with the specified completion status. Optional. Order completion status.
1 – complete orders
0 – incomplete orders

type Only the orders with the specified type Optional. Default value = 3.
2 – fulfilled by eMAG
3 – fulfilled by seller

1.22. Updating orders

You cannot create new orders through the API, you can only read and update them. When updating an order, the seller
should send ALL the fields initially read.

IMPORTANT:
40
 Updating products by reducing their quantities for orders with Online Card payment method is no longer possible.
 Updating product prices is no longer available
 A canceled order can no longer be reactivated if more than 48 hours have passed since cancelation

Resource Example Context

http method: POST

order/save

1.22.1. Removing products from an order

To remove a product from the order send the status=0 for the product or do not send it at all. Products can be removed
from an order only while in status 2 or 3 (in progress or prepared) for orders with payment methods different than
Online card. For returned products (the order is in status 4, finalized), please use the storno route.

IMPORTANT: Removing products for orders with Online Card payment method is no longer possible.

1.22.2. Adding products to an existing order

To add a new product to an existing order, add it to the order by sending the product id (mandatory), name, status and
sale price.

IMPORTANT: virtual products such as internal discounts can be inserted in an order, even if they were not previously
sent to eMAG. Adding these products to an order will not make them available for purchase in the eMAG Marketplace
platform.

1.22.3. Returned products and storno route

A finalized order cannot be modified, it can be fully reversed by changing the order status from finalized (4) to returned
(5) or have only some of the products reversed using a call with is_storno key true.
The following conditions must be met in order for a partial storno to occur:
 Order must be in status 4
 At least one product quantity was reduced

The following scenarios can be used as a guideline for returning products (partial storno) from a finalized order:

Current order status Request isError Order read

status' => 4, status' => 4, FALSE status' => 4,

'products' => 'products' => 'products' =>
array ( array ( array (
0 => 0 => 0 =>
array ( array ( array (
'id' => 1, 'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 1, 'quantity' => 1,
'sale_price' => '123.4567', 'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1, 'status' => 1,
), ), ),
1 => 1 => 1 =>

41
Current order status Request isError Order read

array ( array ( array (

'id' => 2, 'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1, 'status' => 1,
), ), ),
), ), ),
'is_storno'=true

status' => 4, status' => 4, FALSE status' => 4,

'products' => 'products' => 'products' =>
array ( array ( array (
0 => 0 => 0 =>
array ( array ( array (
'id' => 1, 'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2, 'quantity' => 0,
'sale_price' => '123.4567', 'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1, 'status' => 1,
), ), ),
1 => 1 => ),
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 0,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
), ),
'is_storno'=true

status' => 4, status' => 4, FALSE status' => 4,

'products' => 'products' => 'products' =>
array ( array ( array (
0 => 0 => 0 =>
array ( array ( array (
'id' => 1, 'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2, 'quantity' => 0,
'sale_price' => '123.4567', 'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1, 'status' => 1,
), ), ),
1 => 1 => ),
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 0,
), ),
), ),
'is_storno'=true

status' => 4, status' => 4, TRUE The request will be discarded, as you are
'products' => 'products' => trying to modify a finalized order without
array ( array ( is_storno key.
0 => 0 =>

42
Current order status Request isError Order read

array ( array (
'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
1 => 1 =>
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 1,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
), ),

status' => 4, status' => 4, TRUE The request will be discarded, as you are
'products' => 'products' => sending is_storno key without any change
array ( array ( to an order line
0 => 0 =>
array ( array (
'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
1 => 1 =>
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
), ),
'is_storno'=true

status' => 3, status' => 3, TRUE The request will be discarded, as you are
'products' => 'products' => sending is_storno key for an order with a
array ( array ( status different than 4
0 => 0 =>
array ( array (
'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
1 => 1 =>
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),

43
 Current order status Request isError Order read

), ),
'is_storno'=true

status' => 4, status' => 4, TRUE The request will be discarded, as you are
'products' => 'products' => trying to send a negative quantity for a
array ( array ( product
0 => 0 =>
array ( array (
'id' => 1, 'id' => 1,
'product_id' => '1', 'product_id' => '1',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
1 => 1 =>
array ( array (
'id' => 2, 'id' => 2,
'product_id' => '2', 'product_id' => '2',
'quantity' => 2, 'quantity' => 2,
'sale_price' => '123.4567', 'sale_price' => '123.4567',
'status' => 1, 'status' => 1,
), ),
), 2 =>
array (
'id' => 2,
'product_id' => '2',
'quantity' => -1,
'sale_price' => '123.4567',
'status' => 1,
),
),
'is_storno'=true

6. Shipping orders
For electronic deliveries and downloadable goods, please skip this section. Shipping an eMAG Marketplace order
requires the seller to issue an AWB using eMAG Marketplace API.

The resource is AWB and the available actions are read and save

1.23. Saving AWB

To save an AWB just call the API with the following parameters:

Key Description Constraints

order_id Identifies the order Required. Integer value between 1

and 4294967295.
Must be a valid order in the eMAG database,
and must be owned by the seller.

rma_id Identifies the return request Optional. Integer value between 1

and 4294967295.
Must be a valid return request in the eMAG
database, and must be owned by the seller.

44
 Key Description Constraints

sender *Array explained below

receiver *Array explained below

locker_id The pickup point id. Should be filled in with the pickup point id Optional. String value between 3 and 255
received on the order. If filled in, the courier will deliver the parcel in characters
the designated locker.

is_oversize If set to 1, marks the delivery as containing oversized products Required. Value can only be 0 or 1.

insured_value The insured value Optional. Double value between 0 and

999999999

weight The weight of delivery Optional. Double value between 0 and 99999

envelope_number Number of envelopes to be delivered Required. Integer value between 0 and 9999.
If parcel_number is 0, this parameter cannot
be 0

parcel_number Number of parcels to be delivered Required. Integer value between 0 and 999. If
envelope_number is 0, this parameter cannot
be 0

observation Observation text Optional. String value between 0 and 255

cod Cash on delivery Required. Double value between 0 and

999999999

courier_account_i Unique identifier for seller’s courier account. If not provided, a Optional. Integer.
d default account will be used.

pickup_and_return If set to 1, sender expects something in return to this expedition Optional. Value can only be 0 or 1.
(documents, buy-back products, etc).

saturday_delivery If set to 1, sender requests the package to be delivered on Saturday. Optional. Value can only be 0 or 1.

sameday_delivery If set to 1, sender requests the package to be delivered the same day. Optional. Value can only be 0 or 1.

dropoff_locker If set to 1, you will issue the AWB without a request sent to courier to Optional. Value can only be 0 or 1. Used only
pickup your order. If set to 0 or not provided, the courier will pickup for orders.
up the order from your warehouse.

An AWB S/R (sender/receiver) has the following properties:

Key Description Constraints

name S/R's name Required. String value between 3 and 255

contact Receiver's contact person name Required. String value between 1 and 255

phone1 S/R first phone number Required. String value between 8 and 11 digits (only '+' character is allowed at
the beginning of the string)

phone2 S/R second phone number Optional. String value between 8 and 11 digits (only '+' character is allowed at the
beginning of the string)

45
 Key Description Constraints

legal_entity If Receiver is legal entity (applicable only LEGAL_ENTITY_NO = 0

to receiver) LEGAL_ENTITY_YES = 1

locality_id S/R's locality_id Required. Integer value between 1 and 4294967295.

Must be a valid locality in the eMAG database.

street S/R's street Required. String value between 3 and 255

zipcode S/R's zipcode Optional. String value between 1 and 255

IMPORTANT:

 For orders with “pickup” as a delivery method if you do not change the locker id that is already included in the
“shipping_street” field the AWB will be issued as a locker delivery using the proper courier account regardless of the
actual courier account you specified when issuing the AWB.

1.24. Reading AWB

The following filters are available when reading AWBs:

Key Description Constraints

emag_id The eMAG internal barcode id Integer value between 1 and 4294967295.
Must be a valid AWB in eMAG database.

reservation_id The eMAG internal AWB reservation id Integer value between 1 and 4294967295.
Must be a valid AWB in eMAG database.

An AWB has the following properties:

AWB – read

Key – level 1 Key – level 2 Description Constraints Example

emag_id The eMAG internal AWB id Integer. emag_id=243409

order_id The id of the order on which the AWB was Integer. order_id=243409
issued

rma_id The id of the return request on which the Integer. rma_id=243409

AWB was issued

weight The weight of delivery Integer. weight=1

awb_type The type of delivery. Possible values: Integer. awb_type=1

1 – delivery to customer
2 – pickup from customer

awb The AWB List of arrays.

emag_id Integer emag_id=243409

The eMAG internal AWB barcode id

46
 AWB – read

Key – level 1 Key – level 2 Description Constraints Example

awb_number The AWB number String awb_number =

“2EMG00011012”

awb_barcode The AWB barcode String awb_barcode =

“2EMG00011012001”

status The status of the delivery List of arrays.

code The code status of the delivery String. code=”DLV”

name The name of the status of the delivery String. name=”Delivered”

description The description of the status of the delivery String. description=”AWB

delivered”

courier The courier used for issuing the AWB List of arrays.

courier_account_id The eMAG internal courier account id used Integer. courier_account_id=5186

for issuing the AWB

courier_name The eMAG internal courier name used for String. courier_name="SAMEDAY"
issuing the AWB

1.25. Reading AWB PDF files

To download an AWB PDF file call the MARKETPLACE_API_URL/awb URL as in the example below

<html>
Running...<br>
<?
$username = 'user';
$password = 'pass';
$hash = base64_encode($username . ':' . $password);
$headers = array(
'Authorization: Basic ' . $hash
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,'https://marketplace-api.emag.ro/awb/read_pdf?emag_id=9755945&awb_format=A4';
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
echo $result . "\n";
?>
</html>

Optional: You can set the paper format on PDF download link by using the parameter "awb_format=A4" in the link. The
possible values are A4, A5, A6.
47
To download an AWB just call the API with the following parameters:

Key Description Constraints

emag_id The AWB's eMAG id. Integer value between 1 and 4294967295.
Must be a valid AWB in eMAG database.

awb_format The paper format on PDF download The possible values are A4, A5, A6 and ZPL

1.26. Reading AWB ZPL type

To read an AWB in ZPL type call the MARKETPLACE_API_URL/awb URL as in the example below

<html>
Running...<br>
<?
$username = 'user';
$password = 'pass';
$hash = base64_encode($username . ':' . $password);
$headers = array(
'Authorization: Basic ' . $hash
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,'https://marketplace-api.emag.ro/awb/read_zpl?emag_id=9755945';
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
echo $result . "\n";
?>
</html>

Using this request will return a base64 encoded content of the ZPL format as in the example below

Resource Example Context

awb/read_zpl http method: POST

1.27. Counting Localities

In order to issue an AWB you need to submit the correct locality id. You can also use the id from the order.

The resource is locality and the available actions are read and count.

The following filters are available when counting localities:

48
 Key Description Constraints

emag_id The locality with this id Integer

name All localities with this name String of length between 0 and 60

modified All localities modified after this date Date with the 'Y-m-d H:i:s' format

1.28. Reading Localities

The following filters are available when reading localities:

Key Description Constraints

emag_id The locality with this id Integer

name All localities with this name String of length between 0 and 60

region2 The name of the county for which you want String of length between 0 and 60
localities

country Country Alpha-2 code. Available values: String of length 0 and 60

RO – Romania
BG – Bulgaria
HU – Hungary
PL – Poland
EL – Greece
DE – Deutchland

modified All localities modified after this date Date with the 'Y-m-d H:i:s' format

itemsPerPage The maximum number of localities to return. Optional. Integer value between 1 and 100.

currentPage The page offset. Optional. Integer value between 1 and 65535.

When not using the country filter the API will respond only with localities from the platform country.

A locality has the following properties:

Key Description Constraints

emag_id The id of the locality Integer

name The name of the locality String of length between 0 and 60

name_latin The latin name of the locality String of length between 0 and 60

region([1-4]+) Region name String of length between 0 and 60

region([1-4]+)_latin Region name latin version String of length between 0 and 60

geoid Geographic id of the location Integer

modified Last modification date Date with the 'Y-m-d H:i:s' format

49
 Key Description Constraints

country_code Country Alpha-2 code String of length between 0 and 60

1.29. Reading courier accounts

In order to issue an AWB you need to submit the correct courier account id.

Key Description Constraints

account_id The id of the Integer

account

account_display_name The name of the String of length between 0 and 60

account

courier_account_type The type of the Integer. Possible values: 1 - RMA; 2 - Order; 3 - RMA & Order; 4 - Non Marketplace
account

courier_name The name of the String of length between 0 and 60

courier

courier_account_properties The courier account Array. Possible values: 1 – Regular; 4 – Locker delivery
properties

created The account Date with the 'Y-m-d H:i:s' format

creation date

status Account status Integer. Possible values: 1 - Active; 0 - Inactive

7. Processing return requests

A return request consists of customer details, products and reason for returning products. Each return request always
has a status attached. The available statuses are:
1 - incomplete
2 - new
3 - acknowledged
4 - refused
5 - canceled
6 - received
7 - finalized
The resource is RMA and the available actions are read, save.

Return requests fields

The message structure for both read and save actions is detailed below:

RMA – read and save/update

Key – level 1 Key – level 2 Description Constraints Example

emag_id Return request eMAG system ID Required.

50
RMA – read and save/update

Key – level 1 Key – level 2 Description Constraints Example

Type: bigint

id Seller internal return request ID Type: bigint

order_id The id of the order in which the product Required.

to be returned was included Type: bigint

type A flag indicating if the return request Optional. type=3

contains products fulfilled by eMAG or Type: Integer.
by seller. Possible values:
2 – fulfilled by eMAG
3 – fulfilled by seller

invoice_number Invoice of the order in which the Optional.

product to be returned was included Type: varchar
Default value: NULL

customer_name Customer name Required.

Type: varchar

customer_company Customer company info Optional.

Type: varchar
Default value NULL

customer_phone Customer phone no. Required.

Type: varchar

products Product to be returned info Array

id eMAG internal return product line id. Required. Integer id=123

Any update on return product lines value between 1
must use this id. and 9999999.

product_emag_id Product to be returned eMAG ID

product_id Product to be returned seller internal ID Required.

Type: int

quantity Product quantity Required

Type: int

product_name Product name Required.

Type: varchar

return_reason It holds the return reason selected by Required

the customer. In the attached files you Type: int
will find the possible IDs for the return
reasons and their hierarchy.

51
RMA – read and save/update

Key – level 1 Key – level 2 Description Constraints Example

Note: If you opt for a return reason that

has other higher level reason(s), you
will only need to fill in the last level ID
from the hierarchy.

observations Free text notes field. Optional/ Required

Type: text
Note: According to the attached files Default value: NULL
above, the observations key could be
optional (value 0 or value 1) or
mandatory (value 2).

diagnostic Diagnostic after product analysis Optional.

Type: int
Default value NULL

reject_reason Reason of return rejection Optional.

Type: int
Default value NULL

refund_value Refund value Optional.

Type: varchar

awbs Issued AWBs List of arrays.

reservation_id eMAG internal AWB reservation id. Use Optional. reservation_

this id to read an AWB Type: int id= 4528511

pickup_country Required.
Type: Varchar

pickup_suburb Required.
Type: Varchar

pickup_city Required.
Type: Varchar

pickup_address Required.
Type: Varchar

pickup_address_id Id of address already saved on the Optional.

customers' account Type: Int
Default value: NULL

pickup_zipcode Optional.
Type: Varchar
Default value: NULL

pickup_date Returned product pickup date (in case Optional.

of vendor pickup from customer) Type: datetime
Default value NULL

pickup_locality_id The internal eMAG ID of the pickup Required.

address city/locality Type: int

52
RMA – read and save/update

Key – level 1 Key – level 2 Description Constraints Example

pickup_method The product pickup method selected by Required.

the customer when inserting the return Type: int
request. Possible values:
 1 - eMAG courier
 2 - Seller’s own courier
 3 - Sent by client

return_reason It holds the return reason selected by Required

the customer. In the attached files you Type: int
will find the possible IDs for the return
reasons and their hierarchy.

Note: If you opt for a return reason that

has other higher level reason(s), you
will only need to fill in the last level ID
from the hierarchy.

observations Free text notes field. Optional/ Required

Type: text
Note: According to the attached files Default value: NULL
above, the observations key could be
optional (value 0 or value 1) or
mandatory (value 2).

return_type It holds the return type selected by the Required.

customer. Possible values: Type: Int
1 - Replacement with same product
2 - Replacement with a different
product
3 - Refund
4 - Cancel payment contract for this
product
5 - Voucher

return_address_id It will hold the id of the return address Optional.

selected by the vendor in RMA UI Type: Int
Default value: id of
the address set as
default in vendor
profile address
page.

return_tax_value Shipping tax for refused returned Optional.

products (VAT included) Type: Float
The currency used will be the platforms' Default value: NULL
default

customer_account_iban Type: Varchar

53
 RMA – read and save/update

Key – level 1 Key – level 2 Description Constraints Example

Default value: NULL

customer_account_bank Type: Varchar

Default value: NULL

customer_account_beneficiary Type: Varchar

Default value: NULL

replacement_product_emag_id The eMAG ID of the replacement Type: Int

product Default value: NULL

replacement_product_id The seller internal ID of the Type: Int

replacement product Default value: NULL

replacement_product_name Type: Varchar

Default value: NULL

replacement_product_quantity Type: Int

Default value: NULL

date RMA request insertion date Required.

Type: datetime

request_status RMA request status. Possible values: Optional.

1 - Incomplete Type: Int
2 - New
3 - Approved
4 - Refused
5 - Canceled
6 - Received
7 - Finalized

1.30. Return requests filters

When reading return requests the following filters are available:

Key Description Constraints

id Seller internal return request ID

emag_id eMAG return request ID

order_id Order on which the product to be returned was included

product_id Seller internal returned product ID

product_emag_i eMAG returned product ID

d

requests_status Return request status ID

date Return request insertion date

54
 1.31. Status change permissions

The following matrix defines the return request processing flow in eMAG Marketplace:
New status
Actual status 2 - New 3 - Acknowledged 4 - Rejected 5 - Canceled 6 - Received 7 - Finalized
2 - New Yes Yes No Yes No No
3 - Acknowledged No Yes No Yes Yes No
4 - Rejected No No Yes No No No
5 - Canceled No No No Yes No No
6 - Received No No Yes No Yes Yes
7 - Finalized No No No No No Yes
*Some of the statuses were left out by design; these should not be used in any seller implementation

1.32. Return request deliveries

There are two types of possible deliveries for the return requests:

 pick-up requests - courier picks up the returned product(s) from the customer and delivers them to the seller
 regular deliveries - courier delivers the returned/replaced product back to the customer

The delivery requests will be generated using the AWB save resource.

1.33. Examples requests and responses

Resource Example Context

http method: POST

RMA/read
Seller has return requests

http method: POST

RMA/read
Seller does not have return requests

http method: POST

RMA/save

8. Invoice API
The following documentation covers the available APIs used to:
 Read invoice categories
 Read invoice data
 Read customer invoice data

55
 8.1. Reading invoice categories

Every MKTP invoice is included in a category. In order to read all invoice data of a specific MKTP invoice type, first call
the following API without any parameter api-3/invoice/categories.

Resource Example Context

http method: POST

invoice/categories

As a result, we will return a collection of categories and the invoice name as follows:

Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

category Invoice type Type: string category='FC'

name Invoice type name Type: string name='Commission'

Resource Example Context

http method: POST

invoice/categories

8.2. Reading invoice data

URL: api-3/invoice/read

The resource is invoice and for the moment the only available action is read.
Reading invoice data without parameters, will generate a response containing the last 100 invoices.

You can read the invoice details using the following available filters:

Key Description Constraints

category The invoice category from the results displayed when calling the Optional
api-3/invoice/categories API. category='FC'

number The invoice series+number. Optional

number='C-MKTP-100001'

date_start Only invoices created after date_start. Optional

Text in YYYY-mm-dd format

date_end Only invoices created before date_end. Optional

Text in YYYY-mm-dd format

56
 Key Description Constraints

itemsPerPage The maximum number of invoice data to return. Optional. Integer value between 1 and 1000.
Default value=100.

currentPage The page offset. Default value=1.

Reponse:

Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

total_results Number of invoices Type:interger total_results=1

identified

invoices category Invoice type Type: string category='FC'

name Invoice name Type: string name=’Commision’

number Invoice series+number Type: string number='C-MKTP-100001'

date The date when the invoice Text in YYYY- date= '2020-07-24'
was created. mm-dd

is_storno The invoice represents a Type: integer is_storno=1/is_storno=0

reversal of another invoice.

supplier name Supplier name (legal name) Type: string name='Dante International
between 1 and SA'
100 characters.

register_number Registration number Type: string register_number='J40/372/2

between 1 and 002'
50 characters.

cif Unique Identification Code Type: string cif='14399840'

between 1 and
50 characters.

tax_code VAT Number Type: string tax_code='RO14399840'

between 1 and
50 characters.

social_capital Subscribed and paid capital Type: string social_capital='1.210.822

between 1 and RON'
50 characters.

iban Bank account Type: string iban='RO73INGB0001008199

between 1 and 078940'
100 characters.

bank Bank name Type: string bank='ING BANK'

between 1 and
100 characters.

address Headquarters Type: string address=' 148 Virtutii, E47,

between 1 and 060787, Sector 6,
255 characters. Bucuresti'

57
Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

phone_number Phone number Type: string phone=number='402120052

between 1 and 00'
50 characters.

customer name Buyer name (legal name) Type: string name='Test SRL'
between 1 and
100 characters.

register_number Registration number Type: string register_number='

between 1 and JXX/XXX/2002''
50 characters.

cif Unique Identification Code Type: string cif='123456'

between 1 and
50 characters.

tax_code VAT Number Type: string tax_code='RO123456'

between 1 and
50 characters.

iban Bank account Type: string iban='

between 1 and RO00INGB000000000007000
100 characters. 0'

bank Bank name Type: string bank='ING'

between 1 and
100 characters.

country Country Type: string country='Romania'

between 1 and
100 characters.

address Headquarters Type: string address='Strada ABC,

between 1 and Bucuresti'
255 characters.

lines product_name Products/Services Type: text product_name='Comision

Description aferent desfasurator
_dc_082015_1443024267_v
1, conform contract'

unit_of_measure Unit of measure Type: string unit_of_measure='Buc'

between 1 and
20 characters

quantity Quantity Type: double quatity=1

unit_price Unit value Type: double unit_price=100

vat_rate VAT Rate Type: smallint vat_rate=19

value Product value (without VAT) Type: integer value=119

vat_value VAT value Type: integer vat_value=19

payment_term Invoice due date Type: integer payment_term=0

total_without_vat Total invoice without VAT Type: integer total_without_vat=100

58
 Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

total_vat_value Total invoice VAT value Type: integer total_vat_value=19

total_with_vat Total invoice with VAT Type: integer total_with_vat=119

currency Invoice currency Type: string currency='RON'

8.3. Reading customer invoice data

URL: api-3/customer-invoice/read

The resource is customer-invoice and for the moment the only available action is read.
Reading customer invoice data without parameters, will generate a response containing the last 100 invoices.

You can read the customer invoice details using the following available filters:

Key Description Constraints

category The invoice category: normal or storno invoice. Optional

category='normal' / category='storno'

order_id The order which was invoiced. Optional

order_id='148717039'

number The invoice series+number. Optional

number='PRAF100010'

date_start Only invoices created after date_start. Optional

Text in YYYY-mm-dd format

date_end Only invoices created before date_end. Optional

Text in YYYY-mm-dd format

itemsPerPage The maximum number of invoice data to return. Optional. Integer value between 1 and 1000. Default value=100.

currentPage The page offset. Default value=1.

59
Reponse:

Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

total_results Number of invoices Type:interger total_results=1

identified

invoices category Invoice type Type: string category='storno'

order_id The order which was Type: integer order_id='148717039'

invoiced.

number Invoice series+number Type: string number='PRAF101092'

date The date when the Text in YYYY-mm-dd date= '2020-11-11'

invoice was created.

is_storno The invoice represents a Type: integer is_storno=1/is_storno=0

reversal of another
invoice.

reversal_for The invoice which was Type:string reversal_for='PRAF101030'

canceled through this
invoice.

supplier name Supplier name (legal Type: string name=Dobre BA Shop SRL'
name) between 1 and 100
characters.

register_number Registration number Type: string register_number='J40/900/2

between 1 and 50 000'
characters.

cif Unique Identification Type: string cif='10874881'

Code between 1 and 50
characters.

tax_code VAT Number Type: string tax_code='RO10874881'

between 1 and 50
characters.

social_capital Subscribed and paid Type: string social_capital='200 RON'

capital between 1 and 50
characters.

iban Bank account Type: string iban='RO02BTRLRONCRT00

between 1 and 100 W6717503'
characters.

bank Bank name Type: string bank='BANCA TRANSILVANIA

between 1 and 100 S.A.'
characters.

country Country Type: string country='Romania'

between 1 and 100
characters.

address Headquarters Type: string address='Colentina 32, bl 2

between 1 and 255 sc 4 et 33

60
Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

characters. Bucuresti'

customer name Buyer name (legal name) Type: string name='Test Test'
between 1 and 100
characters.

register_number Registration number Type: string register_number=' '

between 1 and 50
characters.

cif Unique Identification Type: string cif=''

Code between 1 and 50
characters.

tax_code VAT Number Type: string tax_code=''

between 1 and 50
characters.

iban Bank account Type: string iban=''

between 1 and 100
characters.

bank Bank name Type: string bank=''

between 1 and 100
characters.

country Country Type: string country='RO'

between 1 and 100
characters.

address Headquarters Type: string address='Strada ABC,

between 1 and 255 Bucuresti'
characters.

lines product_name Products/Services Type: text product_name='Usa de

Description intrare, termopan , model
Roxy white 110x210[61-
110x210] '

unit_of_measure Unit of measure Type: string unit_of_measure='Buc'

between 1 and 20
characters

quantity Quantity Type: double quatity=-1

unit_price Unit value Type: double unit_price=1008.4

vat_rate VAT Rate Type: smallint vat_rate=19

value Product value (without Type: integer value=-1008.4

VAT)

vat_value VAT value Type: integer vat_value=-191.6

total_without_vat Total invoice without Type: integer total_without_vat=-1008.4

VAT

total_vat_value Total invoice VAT value Type: integer total_vat_value=-191.6

61
Key – level 1 Key – level 2 Key – level 3 Description Constraints Example

total_with_vat Total invoice with VAT Type: integer total_with_vat=-1200

currency Invoice currency Type: string currency='RON'

62