Trendyol Partner Programı 2017

TRENDYOL PARTNER (MARKETPLACE) API REFERENCE DOCUMENTATION EN

2

v.3 20.2.2018

CONTENTS TRENDYOL PARTNER (MARKETPLACE) API REFERENCE DOCUMENTATION EN 1

DOCUMENT REVISION HISTORY 3 OVERVIEW 4 API SECURITY 4 TEST ENVIRONMENT INFORMATION 4 PRODUCT ENVIRONMENT INFORMATION 4

METHODS 5 TRANSFER PRODUCTS TO TRENDYOL 5 UPDATE TRANSFERRED PRODUCT’S INFORMATION (RAW DATA) 9 FETCH UNAPPROVED PRODUCTS 9 FETCH APPROVED PRODUCTS 9 UPDATE PRODUCT’S STOCK AND PRICE INFORMATION 11 CHECK BATCHREQUEST RESULT 12 FETCH ORDER PACKAGES 13 NOTIFY PACKAGES AS INVOICED 15 CANCEL ORDER PACKAGE ITEM 16

3

DOCUMENT REVISION HISTORY 1.4 API Addresses changes

2.0 Added live environment information

2.1 Added product transfer and check status information

3.0 Claim information added

4

OVERVIEW The Trendyol Partner API lets you build apps and other integrations for the Trendyol Marketplace. Trendyol Partner API is the primary way of Transferring Products, Updating Stock & Price, Fetching Trendyol Orders in order to work as Marketplace Supplier. API SECURITY Trendyol Partner API uses Basic Auth. Each request has to be include Header information with Auth. Authorization: Basic {base64 encoded username:password}

Sample: Username: test@trendyol.com Şifre: trendyol123 Authorization: Basic dGVzdEB0cmVuZHlvbC5jb206dHJlbmR5b2wxMjM=

To get Username and password information please contact with partnerdestek@trendyol.com TEST ENVIRONMENT INFORMATION To make a successful call, you must provide an Environment URL as {envurl} and a SupplierID {supplierID}. You must contact with Trendyol to learn your SupplierID. For further information please contact with partnerdestek@trendyol.com https://stageapi.trendyol.com/stagesapigw/swagger-ui.html can be used to gather more information or make sample API call. PRODUCT ENVIRONMENT INFORMATION To make a successful call, you must provide an Environment URL as {envurl} and a SupplierID {supplierID}. You must log in to Trendyol Partner Portal from https://partner.trendyol.com All requests must be send to https://api.trendyol.com/sapigw/ production URL.

NOT: Please use swagger files to find further technical details about methods and methods’ filters, requests and response codes and bodies. https://api.trendyol.com/sapigw/swagger-ui.html

5

METHODS TRANSFER PRODUCTS TO TRENDYOL Suppliers should use this method to create product with multiple product variant in Trendyol Marketplace System POST createProducts (Single Variant Example) http://{envurl}/suppliers/{supplierId}/products

Content-Type

application/json

REQUEST

{ "items": [ { "attributes": [ { "attributeName": "Yas Gurubu", "attributeValue": "16-26" }, { "attributeName": "Malzeme", "attributeValue": "Kauçuk" }, { "attributeName": "Theme", "attributeValue": "İlk Bahar Teması" } ], "barcode":"1122338588995", "brand":"Nike", "cargoCompany":"YK", "categoryName":"Ayakkabı", "currencyType":"TRY", "description":"TrendyolMilla Ayakkabı", "gender":"M", "images":[ { "url":"https://pbs.twimg.com/profile_images/594056912615841793/RNhN1WCS.jpg" } ], "listPrice":120, "productMainId":"159357", "quantity":5, "salePrice":100, "stockCode":"a11b2c3d4", "title":"TrendyolMilla Siyah Ayakkabi",

6

"variantAttributes":[ { "attributeName":"Beden", "attributeValue":"M" }, { "attributeName":"Renk", "attributeValue":"Kırmızı" } ], "vatRate":18 } ], "supplierId": 1000 }

POST createProducts (Single Product with 2 Variants) http://{envurl}/suppliers/{supplierId}/products

Content-Type

application/json

REQUEST

{ "items": [ { "attributes": [ { "attributeName": "Yas Gurubu", "attributeValue": "16-26" }, { "attributeName": "Malzeme", "attributeValue": "Kauçuk" }, { "attributeName": "Theme", "attributeValue": "İlk Bahar Teması" } ], "barcode":"1122338588994", "brand":"Nike", "cargoCompany":"YK", "categoryName":"Ayakkabı", "currencyType":"TRY", "description":"TrendyolMilla Ayakkabı", "gender":"M", "images":[ { "url":"https://pbs.twimg.com/profile_images/594056912615841793/RNhN1WCS.jpg" } ], "listPrice":120, "productMainId":"159357", "quantity":5, "salePrice":100, "stockCode":"a11b2c3d3", "title":"TrendyolMilla Siyah Ayakkabi",

7

"variantAttributes":[ { "attributeName":"Beden", "attributeValue":"M" }, { "attributeName":"Renk", "attributeValue":"Kırmızı" } ], "vatRate":18 }, { "attributes": [ { "attributeName": "Yas Gurubu", "attributeValue": "16-26" }, { "attributeName": "Malzeme", "attributeValue": "Kauçuk" }, { "attributeName": "Theme", "attributeValue": "İlk Bahar Teması" } ], "barcode":"1122338588995", "brand":"Nike", "cargoCompany":"YK", "categoryName":"Ayakkabı", "currencyType":"Mavi", "description":"TrendyolMilla Ayakkabı", "gender":"M", "images":[ { "url":"https://pbs.twimg.com/profile_images/594056912615841793/RNhN1WCS.jpg" } ], "listPrice":120, "productMainId":"159357", "quantity":5, "salePrice":100, "stockCode":"a11b2c3d4", "title":"TrendyolMilla Siyah Ayakkabi", "variantAttributes":[ { "attributeName":"Beden", "attributeValue":"M" }, { "attributeName":"Renk", "attributeValue":"Mavi" } ], "vatRate":18 } ], "supplierId": 1000 }

8

NOTE: If a product has more than one variant (such as XL and L size), it is expected that the request will be sent as in multiple instances. Under VariantAttributes, it is possible to send one for each VariantAttributes (eg Color). Wrong Request Example: "variantAttributes":[ { "attributeName":"Renk", "attributeValue":"Kırmızı" }, { "attributeName":"Renk", "attributeValue":"Mavi" }

NOT 2: The products that are submitted in variantAttributes other than Renk and Beden

attributeName cannot be displayed by Trendyol Team. Wrong Request Example: "variantAttributes":[ { "attributeName":"Color", "attributeValue":"Kırmızı" } ]

Parameter Descriptions *BOLD parameters are mandatory.

Parameters Description

product.brand Product Brand

product.barcode Product Barcode

product.title Product Title

product.description Product Description (HTML is allowed)

product.category.name Product Category

product.Listprice Product List Price- PSF

product.Saleprice Product Sale Price- TSF

product.currencyType Product price currency (TRY)

product.images. [List] Proudct image URLs

product.vatRate Product vate rate 0,1,8,18 etc. product.shipmentFirm Cargo Provide (Must be YK)

9

product.quantity Stock amount

product.productMainId Product Main ID

product.gender Gender

product.variantAttributes.Beden Product Size, L,XL,M, W32/L23 etc. product.variantAttributes.Renk Product Color

NOTE: The Barcode information for the Trendyol Partner API system has a prefix that uniquely identifies the product variant. The orders will be fullfilled through the barcodes that sent to the system and all the Product, Stock, Price update operations methods use this Barcode information

UPDATE TRANSFERRED PRODUCT’S INFORMATION (RAW DATA) The Create Products method works as an upsert, and if the submitted barcode is not in the system, the creation is done, if the barcode has been sent, the other values are updated per the information received after the second request.

NOT: Update operations on createProducts update the raw product data in Trendyol system not Live data. The updates made with createProducts are not reflected in the products on sale.

FETCH UNAPPROVED PRODUCTS Products transferred with createProducts to the system should be approved by Trendyol team. filterProducts method can be used to check whether the createProducts method succees or fail GET filterProducts http://{envurl}/suppliers/{supplierId}/products?approved=false

FETCH APPROVED PRODUCTS Products transferred with createProducts to the system should be approved by Trendyol team. filterProducts method can be used to check whether the createProducts method succees or fail. All Approved product’s price and stock information can be updated via update stock and price information GET filterProducts http://{envurl}/suppliers/{supplierId}/products?approved=true

RESPONSE

10

{ "totalElements": 5, "totalPages": 3, "page": 0, "size": 2, "content": [ { "id": "00042e917d80bacda81f7637e02365c8", "batchRequestId": "6cdcf370-7285-471f-8e45-92fdf0af924c", "supplierId": 1024, "createDateTime": 1501841091699, "lastUpdateDate": 1501843028469, "lastPriceChangeDate": 1501843028480, "lastStockChangeDate": 1501841147936, "gender": "", "brand": "TRENDYOLMILLA", "barcode": "86807902889051", "title": "7983 Önü İşlemeli Boyfriend Pantolon-Mavi", "categoryName": "KOLEKSİYON > ALT GİYİM > PANTOLON", "description": "", "stockUnitType": "Adet", "quantity": 2, "listPrice": 30, "salePrice": 100, "vatRate": 8, "images": [ { "url": "http://www.trendyol.com/ProductImages/98393/big/101a07983_mavi.jpg" }, { "url": "http://www.trendyol.com/ProductImages/98393/big/101a07983_mavi-1.jpg" }, { "url": "http://www.trendyol.com/ProductImages/98393/big/101a07983_mavi-2.jpg" }, { "url": "http://www.trendyol.com/ProductImages/98393/big/101a07983_mavi-3.jpg" } ], "attributes": [ {} ], "variantAttributes": [ { "attributeName": "Renk", "attributeValue": "Mavi" }, { "attributeName": "Beden", "attributeValue": "36" } ] }, { "id": "4b5caac9a72f15677da077373d0ee393", "batchRequestId": "f0046af1-278f-4a2c-b6ef-ea2a9c4cdd31", "supplierId": 1024, "createDateTime": 1501841204161, "lastUpdateDate": 1501846443603, "lastPriceChangeDate": 1501846443609, "lastStockChangeDate": 1501846265185, "gender": "", "brand": "TRENDYOLMILLA", "barcode": "8680790286222", "title": "2089 Arkası Fermuarlı Kazak-Ekru", "categoryName": "KOLEKSİYON > ÜST GİYİM > TRİKO",

11

"description": "", "stockUnitType": "Adet", "quantity": 20, "listPrice": 100, "salePrice": 50, "vatRate": 8, "images": [ { "url": "http://www.trendyol.com/ProductImages/107621/big/101a02089_ekru.jpg" }, { "url": "http://www.trendyol.com/ProductImages/107621/big/101a02089_ekru-1.jpg" }, { "url": "http://www.trendyol.com/ProductImages/107621/big/101a02089_ekru-2.jpg" }, { "url": "http://www.trendyol.com/ProductImages/107621/big/101a02089_ekru-3.jpg" } ], "attributes": [ {} ], "variantAttributes": [ { "attributeName": "Renk", "attributeValue": "Ekru" }, { "attributeName": "Beden", "attributeValue": "STD" } ] } ] }

UPDATE PRODUCT’S STOCK AND PRICE INFORMATION This method can be used to update approved product’s stock and sale price. POST updatePriceAndInventory http://{envurl}/suppliers/{supplierId}/products/price-and-inventory

Content-Type

application/json

REQUEST

{

12

"items": [ { "barcode": "BARKODSTRING", "quantity": 12, "salePrice": 69.90 } ] }

RESPONSE – HTTP 200

{ " "batchRequestId": "1541ee80-93ee-40b9-b8e5-b827458968cd" }

CHECK BATCHREQUEST RESULT While createProducts, updatePriceAndInventory methods are processed by the queue in Trendyol System, a batchRequestId information is returned in each successful request result. By checking the "status" field in the return of the service, you can check whether the batch has been completed. If more than one item in the batch results in an error, the failureReasons field can be checked to see error reason. GET getBatchRequestResult http://{envurl}/suppliers/{supplierId}/products/batch-requests/{batchRequestId} RESPONSE

{ "batchRequestId": "b63b62f5-8190-4c48-8964-42c4b5738ba0", "items": [ { "requestItem": { "product": { "brand": "TrendyolMilla", "barcode": "1122334455667", "title": "TrendyolBluz", "description": "Açıklama", "categoryName": "Üst Giyim", "listPrice": 299.9, "salePrice": 209.9, "currencyType": "TRY", "vatRate": 18, "cargoCompany": "YK", "quantity": 5, "stockCode": "a11b2c3d4",

13

"images": [ { "url": "\"https://sitecontent.com/wp-content/uploads/2017/07/9660556476466.jpg\"" } ], "productMainId": "159357", "gender": null, "attributes": [], "variantAttributes": [ { "attributeName": "Beden", "attributeValue": "XL" } ] } }, "status": "SUCCESS", "failureReasons": [] } ], "status": "COMPLETED" }

FETCH ORDER PACKAGES GET orders http://{envurl}/suppliers/{supplierId}/orders

Status Filters:

?status=XXX Available Statuses: Created, Picking, Invoiced, Shipped, Cancelled, Delivered, UnDelivered, Returned, UnSupplied

RESPONSE { "size": 1, "totalPages": 130, "page": 0, "content": [ { "shipmentAddress": { "id": 1577, "firstName": "Bulgak", "lastName": "Erberk", "address1": "773 Özkök Row Apt. 583", "address2": "Apt. 401", "city": "Lake Beğdemirville", "district": "54009 Çetiner Roads",

14

"postalCode": "49010", "countryCode": "TR", "fullName": "Bulgak Erberk", "fullAddress": "773 Özkök Row Apt. 583 Apt. 401 54009 Çetiner Roads Lake Beğdemirville" }, "orderNumber": "84430", "totalPrice": 3756, "taxNumber": null, "invoiceAddress": { "id": 1574, "firstName": "Beker", "lastName": "Kılıççı", "company": "", "address1": "0430 Tütüncü Turnpike Suite 361", "address2": "Suite 448", "city": "Karabulutstad", "district": "96194 Yazıcı Mountain", "postalCode": "81070", "countryCode": "TR", "fullName": "Beker Kılıççı", "fullAddress": "0430 Tütüncü Turnpike Suite 361 Suite 448 96194 Yazıcı Mountain Karabulutstad" }, "customerFirstName": "Esenbike", "customerEmail": "pf+8dezvbod@trendyol.com.test-google-a.com", "customerId": 47122, "customerLastName": "Kılıççı", "id": 44336, "cargoTrackingNumber": 7250003999150, "lines": [ { "quantity": 3, "productId": 64987, "salesCampaignId": 15, "productSize": "M", "merchantSku": "46060", "productName": "Fantastic Frozen Hat", "productCode": 111858, "merchantId": 100, "price": 429, "productColor": "#34563e", "id": 1080, "sku": "106983", "vatBaseAmount": 14, "barcode": "1140693588", "orderLineItemStatusName": "ReadyToShip" }, { "quantity": 1, "productId": 101912, "salesCampaignId": 15, "productSize": "M", "merchantSku": "23707", "productName": "Sleek Fresh Fish", "productCode": 174296, "merchantId": 100, "price": 543, "productColor": "#552b1d", "id": 1081, "sku": "27890", "vatBaseAmount": 13, "barcode": "15870505613", "orderLineItemStatusName": "ReadyToShip" }, { "quantity": 3,

15

"productId": 120406, "salesCampaignId": 15, "productSize": "M", "merchantSku": "85128", "productName": "Fantastic Concrete Sausages", "productCode": 129772, "merchantId": 100, "price": 642, "productColor": "#4e475e", "id": 1082, "sku": "122389", "vatBaseAmount": 11, "barcode": "26082862512", "orderLineItemStatusName": "ReadyToShip" } ], "orderDate": 1514366945859, "tcIdentityNumber": "69058587285", "currencyCode": "TRY" } ], "totalElements": 130 }

NOTE 1: The orderNumber value identifies the main order number in the Trendyol system of that order. The id value at the same level represents the Order Package ID created for that order number.

NOTE 2: If one or more items are cancelled in any order package, the order package will be deleted and a new id value and cargo barcode will be created (for same orderNumber) automatically by the System.

NOTIFY PACKAGES AS INVOICED It is used to notify Trendyol of the creation of the invoice of the order package. Notification of Invoice, a reference to prevent customer-originated cancellations reaching to Trendyol Customer Care Service. PUT updatePackage http://{envurl}/suppliers/{supplierId}/shipment-packages/{shipmentPackageId}

Content-Type

application/json

REQUEST

{ "lines": [ { "lineId": 0, "quantity": 0 }

16

], "params": { "invoiceNumber" :"FTRNUMBER53253434" }, "status": "Invoiced" }

RESPONSE – HTTP 200

NO CONTENT

CANCEL ORDER PACKAGE ITEM Use this method to cancel one or more item in Order Package.

Note: Each order package has a PackageID value. If one of the item is cancelled in the package, the package will be destroyed automatically and new PackageID will be generated and assigned to the new package. PUT updatePackage http://<envurl>/suppliers/{supplierId}/shipment-packages/{shipmentPackageId}

Content-Type

application/json

REQUEST

{ "lines": [ { "lineId": 1, "quantity": 1 } ], "params": {}, "status": "Unsupplied" }

RESPONSE – HTTP 200

NO CONTENT

NOTE : After cancel item request, the order package is deleted and the system automatically

creates an id value and cargo barcode for the same orderNumber. After using cancel item request, fetch Order request must be performed again to get new package id with the same ordernumber

17

GET RETURN PACKAGES VIA EXCEL SFTP This is not an API method. A special job is running just for some companies and Transfer the daily return barcode, return code and order number relation to the supplier’s FTP. A sample excel schema: OrderNumber ReturnCode ReturnBarcode

437534545 72505456654324 135812794781234000000445325235 72505456654323 135812794781234000020345656334 72505456654321 135812794781234300000

OrderNumber: Is the parent OrderNumber of the Trendyol order (you can find this code as orderNumber in getClaims) ReturnCode: The code created by customer from Trendyol.com to make a return (you can find this code as cargoTrackingNumber in getClaims) ReturnBarcode: The code provided by Yurtici Kargo. This coded placed on return package.

GET RETURN(CLAIM) DETAILS Use this method to get bulk return details of a supplier. GET getClaims http://{envurl}//suppliers/{supplierid}/claims?claimItemStatus=WaitingInAction ClaimItemStatus Types: Created, WaitingInAction, Accepted, Cancelled, Rejected,Unresolved Sample Response { "totalElements": 2, "totalPages": 1, "page": 0, "size": 2, "content": [ { "id": 12066, "orderNumber": "46629789", "orderDate": 1519122453301, "customerFirstName": "SEMRA", "customerLastName": "KOÇ", "claimDate": 1519122704453, "cargoTrackingNumber": 9840004431087,

18

"cargoProviderName": "Horoz Kargo Marketplace", "items": [ { "orderLine": { "id": 84640, "productId": 28486541, "productName": "Beyaz Kadın Kolye Web Ürün Tanımı 15 ci1nn47185282ww1x/Sarı, one", "productCode": 9905240, "merchantId": 100, "sku": "ci6new407814728XY47185282kod0", "merchantSku": "TR47185282KP", "productColor": "Sarı", "productSize": " 34", "barcode": "ci6new407814728XY47185282kod0", "price": 15, "vatBaseAmount": 8, "salesCampaignId": 171828, "fulfillmentTypeName": "MARKETPLACE", "fulfillmentTypeId": 7, "productCategory": "Kolye", "dimensionalWeight": 0.2, "lineItems": [ { "id": 243214, "lineItemStatus": { "id": 751, "name": "ReturnDelivered" }, "lineItemStatusHistories": [ { "id": 876076, "status": "ReadyToShip", "createdDate": 1519122454622 }, { "id": 876073, "status": "Approved", "createdDate": 1519122453304 }, { "id": 876072, "status": "Created", "createdDate": 1519122453303 }, { "id": 876084, "status": "ReturnDelivered", "createdDate": 1519122742896 }, { "id": 876080, "status": "Delivered", "createdDate": 1519122485610 }, { "id": 876082, "status": "ReturnReadyToShip", "createdDate": 1519122704694 } ], "shipped": false } ] }, "claimItems": [ {

19

"id": 55616, "orderLineItemId": 243214, "customerClaimItemReason": { "id": 251, "name": "Beğenmeme" }, "trendyolClaimItemReason": { "id": 251, "name": "Beğenmeme" }, "claimItemStatus": { "id": 201, "claimItemStatusName": "WaitingInAction" }, "claimItemStatusHistories": [ { "id": 99955, "claimItemStatus": { "id": 201, "claimItemStatusName": "WaitingInAction" }, "createdDate": 1519122742885 }, { "id": 99953, "claimItemStatus": { "id": 1, "claimItemStatusName": "Created" }, "createdDate": 1519122704474 } ], "countDownValue": 93380236, "note": "" } ] } ] }, { "id": 12067, "orderNumber": "46629789", "orderDate": 1519122453301, "customerFirstName": "SEMRA", "customerLastName": "KOÇ", "claimDate": 1519122715306, "cargoTrackingNumber": 9840004431094, "cargoProviderName": "Horoz Kargo Marketplace", "items": [ { "orderLine": { "id": 84640, "productId": 28486541, "productName": "Beyaz Kadın Kolye Web Ürün Tanımı 15 ci1nn47185282ww1x/Sarı, one", "productCode": 9905240, "merchantId": 100, "sku": "ci6new407814728XY47185282kod0", "merchantSku": "TR47185282KP", "productColor": "Sarı", "productSize": " 34", "barcode": "ci6new407814728XY47185282kod0", "price": 15, "vatBaseAmount": 8, "salesCampaignId": 171828, "fulfillmentTypeName": "MARKETPLACE", "fulfillmentTypeId": 7,

20

"productCategory": "Kolye", "dimensionalWeight": 0.2, "lineItems": [ { "id": 243213, "lineItemStatus": { "id": 751, "name": "ReturnDelivered" }, "lineItemStatusHistories": [ { "id": 876077, "status": "ReadyToShip", "createdDate": 1519122454639 }, { "id": 876079, "status": "Delivered", "createdDate": 1519122485595 }, { "id": 876085, "status": "ReturnDelivered", "createdDate": 1519122896874 }, { "id": 876071, "status": "Approved", "createdDate": 1519122453302 }, { "id": 876070, "status": "Created", "createdDate": 1519122453302 }, { "id": 876083, "status": "ReturnReadyToShip", "createdDate": 1519122715546 } ], "shipped": false } ] }, "claimItems": [ { "id": 55617, "orderLineItemId": 243213, "customerClaimItemReason": { "id": 251, "name": "Beğenmeme" }, "trendyolClaimItemReason": { "id": 251, "name": "Beğenmeme" }, "claimItemStatus": { "id": 201, "claimItemStatusName": "WaitingInAction" }, "claimItemStatusHistories": [ { "id": 99956, "claimItemStatus": { "id": 201, "claimItemStatusName": "WaitingInAction"

21

}, "createdDate": 1519122896855 }, { "id": 99954, "claimItemStatus": { "id": 1, "claimItemStatusName": "Created" }, "createdDate": 1519122715342 } ], "countDownValue": 93534151, "note": "" } ] } ] } ] }

GET RETURN REASON CODES Use this method to get return reason codes to approve return items GET getClaimItemReasons http://ENVURL/claim-item-reasons/platform [ { "id": 51, "name": "Sebep Yok" }, { "id": 101, "name": "Depo Kayıp" } ]

APPROVE RETURN(CLAIM) ITEMS Use this method to approve return items PUT ApproveClaim https://stageapi.trendyol.com/stagesapigw/suppliers/100/claims/approve { "items": [ {

22

"barcode": "string", "claimNote": "string", "quantity": 0, "reasonId": 0 } ], "orderNumber": "string" }