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://api.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://api.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
A1Posta1postYes
ABF FreightabfYes
ACS CourieracscourierYes
AeroFlashaeroflashYes
Afghan Postafghan-postNo
Amazon Logistics UKamazon-uk-apiYes
Amazon Logistics USamazonYes
An Postan-postYes
Anguilla Postal Serviceanguilla-postNo
APC Postal LogisticsapcYes
AramexaramexYes
Asendia UKasendia-ukYes
Asendia USAasendia-usaYes
Australia Postaustralia-postYes
Austrian Postaustrian-postYes
Austrian Post Registeredaustrian-post-registeredYes
Bahrain Postbahrain-postNo
Bangladesh Post Officebangladesh-postNo
Belgium Post DomesticbpostYes
Belgium Post Internationalbpost-internationalYes
BelposhtabelpostYes
BH Postabh-postaNo
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
Deltec Courierdeltec-courierYes
Deutsche Postdeutsch-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
Direct LinkdirectlinkYes
DPDdpdYes
DPD Germanydpd-deYes
DPD Polskadpd-polandYes
DPD UKdpd-ukYes
DTDC IndiadtdcYes
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
Ghana Postghana-postNo
GlobegisticsglobegisticsYes
GLSglsYes
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
i-parceli-parcelYes
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 du Senegalposte-senegalNo
La Poste Tunisienneposte-tunisienneNo
Landmark Globallandmark-globalYes
LaserShiplasershipYes
Latvijas Pastslatvijas-pastsNo
LibanPostlibanpostNo
Lietuvos Pastaslietuvos-pastasYes
Magyar Postamagyar-postaYes
Makedonska Postamakedonska-postaNo
Malaysia Pos Daftarmalaysia-post-posdaftarYes
Maldives Postmaldives-postNo
MaltaPostmaltapostNo
Mauritius Postmauritius-postNo
Mondial RelaymondialrelayYes
MRWmrw-spainYes
Multipackmexico-multipackYes
myHermes UKmyhermes-ukYes
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
Oman Postoman-postNo
OnTracontracYes
OPToptNo
OPT de Nouvelle-Caledonieopt-nouvelle-caledonieNo
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
PTT Postaptt-postaYes
PurolatorpurolatorYes
Qatar Postqatar-postNo
Red Expressred-expressYes
Redpackmexico-redpackYes
Royal Mailroyal-mailNo
RL Carriersrl-carriersYes
RPX IndonesiarpxYes
Russian Postrussian-postYes
S.F Internationalsfb2cYes
SafexpresssafexpressYes
SagawasagawaYes
Saudi Postsaudi-postYes
SDA Express Courieritaly-sdaYes
SelektvrachtselektvrachtYes
Senda Expressmexico-senda-expressYes
SendlesendleYes
SerpostserpostNo
SEUR Espana (Domestico)spanish-seurYes
SEUR Portugal (Domestico)portugal-seurYes
SF Expresssf-expressYes
Singapore Postsingapore-postYes
Singapore SpeedPostsingapore-speedpostYes
SiodemkasiodemkaYes
Skynet Malaysiaskynet-malaysiaYes
SkyNet Wordwide ExpressskynetworldwideYes
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
Thailand Postthailand-postYes
TNTtntYes
TNT Australiatnt-auYes
TNT Francetnt-frYes
TNT Italiatnt-itYes
TNT UKtnt-ukYes
Toll Global Expresstoll-global-expressNo
Toll Prioritytoll-priorityYes
TTPostttpostNo
UK Mailuk-mailYes
UkrPoshtaukrposhtaYes
UPSupsYes
UPS Freightups-freightYes
uShipushipYes
USPSuspsYes
Vanuatu Postvanuatu-postNo
Vietnam PostvnpostYes
Vietnam Post EMSvnpost-emsYes
WhistlwhistlYes
XendxendYes
YakityakitYes
YanwenyanwenYes
Yemen Postyemen-postNo
YodelyodelYes
Yodel Internationalyodel-internationalYes
YRC FreightyrcYes
ZampostzampostNo
ZimpostzimpostNo

Countries requiring postal codes#

Shipping profiles require valid postal code inputs for the following countries:

Country nameiso_code
Åland IslandsAX
AlbaniaAL
AlgeriaDZ
American SamoaAS
AndorraAD
ArgentinaAR
ArmeniaAM
AustraliaAU
AustriaAT
AzerbaijanAZ
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BermudaBM
BhutanBT
Bosnia and HerzegovinaBA
BrazilBR
British Indian Ocean TerritoryIO
British Virgin IslandsVG
BruneiBN
BulgariaBG
CambodiaKH
CanadaCA
Cape VerdeCV
Cayman IslandsKY
ChileCL
ChinaCN
Christmas IslandCX
Cocos (Keeling) IslandsCC
ColombiaCO
Costa RicaCR
CroatiaHR
CyprusCY
Czech RepublicCZ
DenmarkDK
Dominican RepublicDO
EcuadorEC
EgyptEG
El SalvadorSV
EstoniaEE
EthiopiaET
Falkland Islands (Malvinas)FK
Faroe IslandsFO
FinlandFI
FranceFR
French GuianaGF
French PolynesiaPF
GeorgiaGE
GermanyDE
GibraltarGI
GreeceGR
GreenlandGL
GuadeloupeGP
GuamGU
GuatemalaGT
GuernseyGG
GuineaGN
Guinea-BissauGW
HaitiHT
Heard Island and McDonald IslandsHM
Holy See (Vatican City State)VA
HondurasHN
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
IranIR
IraqIQ
IrelandIE
Isle of ManIM
IsraelIL
ItalyIT
JapanJP
JerseyJE
JordanJO
KazakhstanKZ
KenyaKE
KuwaitKW
KyrgyzstanKG
LaosLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacedoniaMK
MadagascarMG
MalaysiaMY
MaldivesMV
MaltaMT
Marshall IslandsMH
MartiniqueMQ
MauritiusMU
MayotteYT
MexicoMX
Micronesia, Federated States ofFM
MoldovaMD
MonacoMC
MongoliaMN
MontenegroME
MoroccoMA
Myanmar (Burma)MM
NepalNP
New CaledoniaNC
New ZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
Norfolk IslandNF
Northern Mariana IslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
Papua New GuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PolandPL
PortugalPT
Puerto RicoPR
ReunionRE
RomaniaRO
RussiaRU
Saint BarthélemyBL
Saint HelenaSH
Saint Martin (French part)MF
Saint Pierre and MiquelonPM
Saint Vincent and the GrenadinesVC
San MarinoSM
Saudi ArabiaSA
SenegalSN
SerbiaRS
SingaporeSG
SlovakiaSK
SloveniaSI
SomaliaSO
South AfricaZA
South Georgia and the South Sandwich IslandsGS
South KoreaKR
SpainES
Sri LankaLK
Svalbard and Jan MayenSJ
SwazilandSZ
SwedenSE
SwitzerlandCH
TaiwanTW
TajikistanTJ
TanzaniaTZ
ThailandTH
The NetherlandsNL
TunisiaTN
TurkeyTR
TurkmenistanTM
Turks and Caicos IslandsTC
UkraineUA
United KingdomGB
United StatesUS
United States Minor Outlying IslandsUM
UruguayUY
U.S. Virgin IslandsVI
UzbekistanUZ
VenezuelaVE
VietnamVN
Wallis and FutunaWF
Western SaharaEH
ZambiaZM

Country Holidays#

Mapping of holidays that each country observes and it's corresponding ID.

United Statesholiday_id
New Years Day1
Martin Luther King Jr. Day2
Presidents Day3
Memorial Day4
Juneteenth5
Independence Day6
Labor Day7
Columbus Day8
Veterans Day9
Thanksgiving Day10
Christmas Day11
Canadaholiday_id
Good Friday12
Easter13
Victoria Day14
Canada Day15
Truth and Reconciliation Day16
Rememberance Day17
Civic Holiday18
Boxing Day19
New Years Day20
Labour Day21
Thanksgiving Day22
Christmas Day23