Fulfillment Tutorial

important

These tutorials are subject to change as endpoints change during our feedback period development. We welcome your feedback! If you find an error or have a suggestion, please post it in the Open API GitHub Repository.

Fulfillment covers all shipping and handling activities required to ship and return customer orders. Additionally, when your app submits tracking information for shipping, Etsy triggers the final calculations for the purchase transaction, including Value Added Tax (VAT), tax, and shipping costs, resulting in complete receipts.

Throughout this tutorial, the instructions reference REST resources, endpoints, parameters, and response fields, which we cover in detail in Request Standards and URL Syntax.

Authorization and x-api-key header parameters#

The endpoints in this tutorial require an OAuth token in the header with transactions_r and transactions_w scope. See the Authentication topic for instructions on how to generate an OAuth token with these scopes.

In addition, all Open API V3 requests require the x-api-key: parameter in the header with your shop's Etsy App API Key keystring, which you can find in Your Apps.

Fulfilling Digital Orders#

A seller typically does not need to do anything to fulfill orders for digital products after creating the listing and uploading files for buyers to buy. Buyers can download files from their purchase history forever once purchased, even if the seller stops offering that digital product for sale. However, there are a few important details a seller should be aware of following the fulfillment of a digital order:

  1. Files purchased by buyers in the past aren't automatically updated when you update the listing with newer version of the file.
  2. You must include any tax amounts applicable to the purchase in the purchase price, as Etsy doesn't add tax automatically to digital products except for calculated Value Added Tax (VAT) amounts. See How VAT Works on Digital Items for more information on calculated VAT for digital products.

Fulfilling Physical Product Orders#

You fulfill physical product orders by shipping them and using the createReceiptShipment to add the carrier and tracking information to your shop and customers. To get a list of shipping carriers for a shop, use getShippingCarriers or see Tracking updates for shipping carriers below. Etsy posts the final transaction total immidately after a seller posts shipping details, so the response from createReceiptShipment includes calculated taxes, discounts, gift wrap prices, etc. Additionally, successful createReceiptShipment requests send a notification email to the buyer.

Sellers enter shipping costs as part of a shipping profile using Shipping Profile endpoints. See the listings tutorial for instructions on adding a shipping profile to a listing. Sellers can purchase shipping through Etsy, but the Open API v3 does not include an endpoint to order shipping, so the seller must enter costs into shipping profiles, purchase shipping, and print shipping labels themselves. See How to Purchase Etsy Shipping Labels for all carriers Etsy supports directly in the seller tools.

The following procedure adds shipping tracking information to a receipt:

  1. Form a valid URL for createReceiptShipment, which must include a shop_id for the shop and the receipt_id for the purchase. For example, if your shop_id is 12345678 and your receipt_id is 090898651, the createShopSection URL is:

    https://openapi.etsy.com/v3/application/shops/12345678/receipts/090898651/tracking
  2. Build the createReceiptShipment request body, which must include tracking_code string provided by the carrier and carrier_name string to identify the carrier. Etsy supports tracking updates for many shipping carriers as determined by the carrier_name parameter. See Tracking updates for shipping carriers below.

  3. Execute a createReceiptShipment POST request with a transactions_w scope OAuth token and x-api-key. For example, a createReceiptShipment request to create the "Spiral Carpet" section might look like the following:

var headers = new Headers();
headers.append("Content-Type", "application/x-www-form-urlencoded");
headers.append("x-api-key", "2lk6cu87j83a15eqnfmf7ysk");
headers.append("Authorization", "Bearer 12345678.jKBPLnOiYt7vpWlsny_lDKqINn4Ny_jwH89hA4IZgggyzqmV_bmQHGJ3HOHH2DmZxOJn5V1qQFnVP9bCn9jnrggCRz");
var urlencoded = new URLSearchParams();
urlencoded.append("tracking_code", "KB6NANRE9noji32oOU34h");
urlencoded.append("carrier_name", "fedex");
var requestOptions = {
method: 'POST',
headers: headers,
body: urlencoded,
redirect: 'follow'
};
fetch("https://openapi.etsy.com/v3/application/shops/12345678/receipts/090898651/tracking", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Tracking updates for shipping carriers#

Etsy supports tracking updates for several carriers, determined by the carrier_name submitted with a createShippingReceipt request. Tracking updates provide a tracking link in the shipping notification email and displays tracking updates for the shipment on Etsy.

The table below lists known carriers, the carrier_name parameter values, and whether Etsy supports tracking updates for that organization.

Carriercarrier_nameTracking Updates
4PX Worldwide Express4pxYes
ABF FreightabfYes
ACS CourieracscourierYes
APC Postal LogisticsapcYes
AeroFlashaeroflashYes
Afghan Postafghan-postNo
Amazon Logistics UKamazon-uk-apiYes
Amazon Logistics USamazonYes
An Postan-postYes
Anguilla Postal Serviceanguilla-postNo
AramexaramexYes
Asendia UKasendia-ukYes
Asendia USAasendia-usaYes
Australia Postaustralia-postYes
Austrian Postaustrian-postYes
Austrian Post Registeredaustrian-post-registeredYes
BH Postabh-postaNo
Bahrain Postbahrain-postNo
Bangladesh Post Officebangladesh-postNo
Belgium Post DomesticbpostYes
Belgium Post Internationalbpost-internationalYes
BelposhtabelpostYes
Blue DartbluedartYes
BotswanaPostbotswanapostNo
Brunei Postal Servicesbrunei-postNo
Bulgarian PostsbgpostYes
Cambodia Postcambodia-postYes
Canada Postcanada-postYes
Canpar CouriercanparYes
Ceska Postaceska-postaYes
China EMSchina-emsYes
China Postchina-postYes
Chit ChatschitchatsYes
Chronopost Francechronopost-franceYes
Chronopost Portugalchronopost-portugalYes
Chunghwa Posttaiwan-postYes
City Linkcity-linkYes
ColissimocolissimoYes
Collect+collectplusYes
Correios de Brasilbrazil-correiosYes
Correios de Macaucorreios-macauNo
Correios de Portugal (CTT)portugal-cttYes
Correo Argentino Domesticcorreo-argentinoYes
Correo Argentino Internationalcorreo-argentino-intlYes
Correo Uruguayocorreo-uruguayoNo
Correos - Espanaspain-correos-esYes
Correos Chilecorreos-chileYes
Correos De Mexicocorreos-de-mexicoYes
Correos de Costa Ricacorreos-de-costa-ricaYes
Correos del Ecuadorcorreos-ecuadorNo
Courier PostcourierpostYes
Couriers Pleasecouriers-pleaseYes
Cyprus Postcyprus-postYes
DHL Beneluxdhl-beneluxYes
DHL ExpressdhlYes
DHL Germanydhl-germanyYes
DHL Global Maildhl-global-mailYes
DHL Netherlandsdhl-nlYes
DHL Parcel NLdhlparcel-nlYes
DHL Polskadhl-polandYes
DHL Spain Domesticdhl-esYes
DHL eCommercedhl-global-mail-asiaYes
DPDdpdYes
DPD Germanydpd-deYes
DPD Polskadpd-polandYes
DPD UKdpd-ukYes
DTDC IndiadtdcYes
Deltec Courierdeltec-courierYes
Deutsche Postdeutsch-postYes
Direct LinkdirectlinkYes
EC-Firstclassec-firstclassYes
Egypt Postegypt-postNo
El Correoel-correoNo
Elta Courierelta-courierYes
Empostemirates-postYes
Empresa de Correos de Boliviacorreos-boliviaNo
EstafetaestafetaYes
EstesestesYes
Estonian Postestonian-postNo
Ethiopian Postal Serviceethiopian-postNo
EvergreenevergreenNo
Fastway Australiafastway-auYes
Fastway Couriersfastway-irelandYes
Fastway New Zealandfastway-nzYes
Fastways Couriers South Africafastway-zaYes
FedExfedexYes
Fedex UK (Domestic)fedex-ukYes
First Flight Couriersfirst-flightYes
Flash Courierflash-courierYes
Freightquote by C. H. RobinsonfreightquoteYes
GATI-KWEgati-kweYes
GLSglsYes
Ghana Postghana-postNo
GlobegisticsglobegisticsYes
GreyhoundgreyhoundYes
Guernsey Postguernsey-postNo
Hay Posthay-postNo
Hellenic Posthellenic-postNo
Hermeshermes-deYes
Hermes Italyhermes-itYes
Hermes UKhermesYes
Hong Kong Posthong-kong-postYes
Hrvatska Postahrvatska-postaYes
India Postindia-postYes
India Post Internationalindia-post-intYes
Interlink Expressinterlink-expressYes
International Seurinternational-seurYes
IpostelipostelNo
Iran Postiran-postNo
IslandsposturislandsposturNo
Isle of Man Post Officeisle-of-man-postNo
Israel Postisrael-postYes
Israel Post Domesticisrael-post-domesticYes
Jamaica Postjamaica-postNo
Japan Postjapan-postYes
Jersey Postjersey-postNo
Jordan Postjordan-postNo
KazpostkazpostNo
Korea PostkpostYes
Korea Post EMSkorea-postYes
Kuehne + NagelknYes
La Postela-poste-colissimoYes
La Poste Monacoposte-monacoNo
La Poste Tunisienneposte-tunisienneNo
La Poste du Senegalposte-senegalNo
Landmark Globallandmark-globalYes
LaserShiplasershipYes
Latvijas Pastslatvijas-pastsNo
LibanPostlibanpostNo
Lietuvos Pastaslietuvos-pastasYes
MRWmrw-spainYes
Magyar Postamagyar-postaYes
Makedonska Postamakedonska-postaNo
Malaysia Pos Daftarmalaysia-post-posdaftarYes
Maldives Postmaldives-postNo
MaltaPostmaltapostNo
Mauritius Postmauritius-postNo
Mondial RelaymondialrelayYes
Multipackmexico-multipackYes
Nacexnacex-spainYes
New Zealand Postnew-zealand-postYes
Nexivetntpost-itYes
Nieuwe Post Nederlandse Antillen (PNA)nieuwe-post-nederlandse-antillen-pnaNo
Nigerian Postal ServicenipostYes
Nova Poshtanova-poshtaYes
OCAoca-arYes
OPEKopekYes
OPToptNo
OPT de Nouvelle-Caledonieopt-nouvelle-caledonieNo
Oman Postoman-postNo
OnTracontracYes
PTT Postaptt-postaYes
Pakistan Postpakistan-postNo
Parcelforce Worldwideparcel-forceYes
Poczta Polskapoczta-polskaYes
Pos Indonesiapos-indonesiaYes
Pos Indonesia Internationalpos-indonesia-intYes
Pos Malaysiamalaysia-postYes
Post Arubapost-arubaNo
Post Fijipost-fijiNo
Post Luxembourgpost-luxembourgNo
PostNL DomesticpostnlYes
PostNL Internationalpostnl-internationalYes
PostNL International 3Spostnl-3sYes
PostNorddanmark-postYes
PostNord LogisticspostnordYes
PostapostaNo
Posta Kenyaposta-kenyaNo
Posta Moldoveiposta-moldoveiNo
Posta Romanaposta-romanaYes
Posta Shqiptareposta-shqiptareNo
Posta Slovenijeposta-slovenijeNo
Posta Srbijeposta-srbijeNo
Posta Ugandaposta-ugandaNo
Poste Italianeposte-italianeYes
Poste Italiane Paccocelereposte-italiane-paccocelereYes
Poste Marocposte-marocNo
Posten ABsweden-postenYes
Posten Norgeposten-norgeYes
PostipostiYes
PostmatespostmatesYes
PurolatorpurolatorYes
Qatar Postqatar-postNo
RL Carriersrl-carriersYes
RPX IndonesiarpxYes
Red Expressred-expressYes
Redpackmexico-redpackYes
Royal Mailroyal-mailNo
Russian Postrussian-postYes
S.F Internationalsfb2cYes
SDA Express Courieritaly-sdaYes
SEUR Espana (Domestico)spanish-seurYes
SEUR Portugal (Domestico)portugal-seurYes
SF Expresssf-expressYes
SafexpresssafexpressYes
SagawasagawaYes
Saudi Postsaudi-postYes
SelektvrachtselektvrachtYes
Senda Expressmexico-senda-expressYes
SendlesendleYes
SerpostserpostNo
Singapore Postsingapore-postYes
Singapore SpeedPostsingapore-speedpostYes
SiodemkasiodemkaYes
SkyNet Wordwide ExpressskynetworldwideYes
Skynet Malaysiaskynet-malaysiaYes
Skynet Worldwide ExpressskynetworldwideYes
Slovenska postaslovenska-postaNo
South Africa Post OfficesapoYes
Stallion ExpressstallionexpressYes
StarTrackstar-trackYes
Swiss Postswiss-postYes
TA-Q-BIN Hong Kongtaqbin-hkYes
TA-Q-BIN Japantaqbin-jpYes
TA-Q-BIN Malaysiataqbin-myYes
TA-Q-BIN Singaporetaqbin-sgYes
TGXtgxYes
TNTtntYes
TNT Australiatnt-auYes
TNT Francetnt-frYes
TNT Italiatnt-itYes
TNT UKtnt-ukYes
TTPostttpostNo
Thailand Postthailand-postYes
Toll Global Expresstoll-global-expressNo
Toll Prioritytoll-priorityYes
UK Mailuk-mailYes
UPSupsYes
UPS Freightups-freightYes
USPSuspsYes
UkrPoshtaukrposhtaYes
Vanuatu Postvanuatu-postNo
Vietnam PostvnpostYes
Vietnam Post EMSvnpost-emsYes
WhistlwhistlYes
XendxendYes
YRC FreightyrcYes
YakityakitYes
YanwenyanwenYes
Yemen Postyemen-postNo
YodelyodelYes
Yodel Internationalyodel-internationalYes
ZampostzampostNo
ZimpostzimpostNo
i-parceli-parcelYes
myHermes UKmyhermes-ukYes
uShipushipYes