Providing label

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

When a shipping label is required, Fulfil will send a POST request to the /label endpoint with the following payload.

{
  "account_id": "123456789",
  "service_code": "S1",
  "origin": {
    "name": "Joe Santiego",
    "street1": "444 Castro St",
    "street2": "Suite 1200",
    "city": "Mountain view",
    "zip": "94041",
    "country": "US",
    "state": "CA",
    "email": "[email protected]",
    "phone": "+18978678653",
    "company": "Fulfil.IO Inc.",
    "validation_status": null,
    "address_type": null,
    "tax_identification": null
  },
  "destination": {
    "name": "Tony Douglas",
    "street1": "157 W 57th St",
    "street2": "Suite 1200",
    "city": "New York",
    "zip": "10019",
    "country": "US",
    "state": "NY",
    "email": "[email protected]",
    "phone": "+18979671111",
    "company": null,
    "validation_status": null,
    "address_type": null,
    "tax_identification": null
  },
  "packages": [
    {
      "length": 4,
      "width": 4,
      "height": 5,
      "dimension_unit": "in",
      "weight": 7,
      "weight_unit": "lb",
      "carrier_code": null,
      "machinable": false,
      "dhl_ecommerce_dangerous_goods_category": null,
      "easyship_category": null,
      "description": "Merchandise",
      "amount": 99.0,
      "quantity": null,
      "amount": null,
      "reference": "CS123PKG231",
      "lines": [
        {
          "sku": "IPHONE-7",
          "quantity": 1,
          "channel_identifier": null,
          "weight": 6,
          "weight_uom": "lb",
          "unit_price": 99.00,
          "uom": "u"
        }
      ]
    },
    {
      "length": 10,
      "width": 5,
      "height": 5,
      "dimension_unit": "in",
      "weight": 7,
      "weight_unit": "lb",
      "carrier_code": null,
      "machinable": false,
      "dhl_ecommerce_dangerous_goods_category": null,
      "easyship_category": null,
      "description": "Merchandise",
      "amount": 80.0,
      "quantity": null,
      "amount": null,
      "reference": "CS123PKG232",
      "lines": [
        {
          "sku": "MAC-PRO",
          "quantity": 2,
          "channel_identifier": null,
          "weight": 6,
          "weight_uom": "lb",
          "unit_price": 40.00,
          "uom": "u"
        }
       ]
    }   
  ],
  // The "customs" key will only have a value for international shipments. 
  // Otherwise, for domestic shipments it will have a null value.
  "customs": {
    "customs_certify": true,
    "contents_type": "other",
    "customs_signer": null,
    "contents_explanation": "Electronic Items",
    "non_delivery_option": "return",
    "items": [
      {
        "description": "iPhone 7",
        "quantity": 1,
        "value": 99,
        "currency": "USD",
        "company_currency": "EUR",
        "value_in_company_currency": 84,
        "weight": 1,
        "weight_unit": "lb",
        "hs_code": null,
        "sku": null,
        "manufacturer_product_id": null,
        "standard_manufacturer_product_id": null,
        "country_of_origin": "US",
        "_options": {}
      },
      {
        "description": "MacBook Pro",
        "quantity": 2,
        "value": 40,
        "currency": "USD",
        "company_currency": "EUR",
        "value_in_company_currency": 34,
        "weight": 6,
        "weight_unit": "lb",
        "hs_code": null,
        "sku": null,
        "manufacturer_product_id": null,
        "standard_manufacturer_product_id": null,
        "country_of_origin": "US",
        "_options": {}
      }
    ],
    "incoterm": null,
    "invoice_number": null,
    "eel": null,
    "pfc": null,
    "exporter_tax_id_type": null,
    "exporter_tax_id": null,
    "exporter_eori_number": null,
    "importer": null
  },
  "customer": {
    "email": "[email protected]"
  },
  "options": {
    "reference1": "SO123 #123",
    "reference2": "CS145",
    "is_return": false,
    "request_confirmation": "signature",
    "insurance_amount": "123.99",
    "shipping_date": "2025-12-02",
    "label_type": "PNG" # can be either PNG or ZPL
  }
}

Expected Response

The response must include the following attributes

  • tracking_number - An end user facing tracking number
  • amount - The total shipping cost that will be charged to the merchant
  • currency - The currency of the shipping cost. If it is not sent, it defaults to USD.
  • packages[].label - Base 64 encoded PNG labels
{
  "tracking_number": "12345",
  "amount": "120.00",
  "packages": [{
      "label": "iVBORw0KGgoAAAANSUhEUgAAAaYAAAJ6CAYAAAB"
  }]
}

A fully detailed response can include

{
  "tracking_number": "12345",
  "tracking_url": "https://your-service.com/track/12345",
  "carrier_identifier": "usps",
  "amount": "120.00",
  "currency": "CAD",
  "packages": [{
          "tracking_number": "12345",
          "label": "iVBORw0KGgoAAAANSUhEUgAAAaYAAAJ6CAYAAAB",
          "tracking_url": "https://your-service.com/track/12345"
      },
      {
          "tracking_number": "54321",
          "label": "iVBORw0KGgoAAAANSUhEUgAAAaYAAAJ6CAYCCB",
          "tracking_url": "https://your-service.com/track/54321"
      }
  ]
}

Idempotency

When generating shipping labels, especially for multi-package shipments, proper idempotency handling is crucial to prevent duplicate label creation and ensure consistent results across retries.

We recommend using the package reference value as the idempotency key, rather than the shipment-level reference1 or reference2. This is because:

  1. Multiple packages in a single shipment need individual labels
  2. Each package might need to be retried independently
  3. Shipment-level references would prevent generating labels for subsequent packages

Label type

When sending data to the /label endpoint, the options object within the shipment payload includes a key named label_type. This key specifies the expected format for the label data.

Supported Label Types

Fulfil supports two types of label formats:

  1. PNG
    • When using "PNG" as the label type, the PNG label content should be provided in Base64 encoded format.
  2. ZPL
    • For "ZPL" label types, the label content is expected to be raw ZPL (Zebra Programming Language) content. In this case, encoding is not required, and the raw label data can be directly sent in the label data field.

List of supported carrier identifiers

Fulfil carrier identifierCarrier Name
4px4PX
aaa_cooperAAA Cooper Transportation
ab_courrierA&B Courier
abfABF
aciACI
ag_systemsAssociated Global Systems
amazon_logisticsAmazon Logistics
amazon_mwsAmazonMws
apcAPC
apgAPG
aramexAramex
arrow_xlArrowXL
asendiaAsendia
asendia_hkAsendia HK
aslASL Distribution
australia_postAustralia Post
axlehire_v3AxlehireV3
better_trucksBetter Trucks
blue_dartBluedart
bniBrunswick News
bopgBolt Delivery
boxberryBoxberry
boxcBoxC
brinks_globalBrinks Global Services USA
brtBRT
cainiaoCainiao
canada_postCanada Post
canparCanpar
cargorsCargors Pallet Carrier
cargusCargus
cdlCDL Delivers
central_transportCentral Transport
cevaCEVA
china_emsEMS
china_postChina Post
chronopostChronopost
cirroCIRRO: Global E-Commerce Logistics
cityxCity Logistics Transport
cne_expressCNE Express
colis_priveColis Prive
colissimoColissimo
columbus_last_mileCDL Last Mile Solutions
correiosCorreios
correos_chileCorreos Chile
correos_costa_ricaCorreos Costa Rica
couriers_pleaseCouriersPlease
cteCalifornia Transportation Enterprises
dachserDachser
dai_postDai Post
daylight_transportDaylight Transport
delhiveryDelhivery
delivDeliv
deliverrDeliverr
deutsche_postDeutsche Post
dhl_ecommerceDHL eCommerce
dhl_ecommerce_asiaDHL eCommerce Asia
dhl_expressDHL Express
dhl_freightDHL Freight
dhl_germanyDHL Germany
dhl_global_mailDHL Global Mail (Deprecated)
dhl_globalmail_internationalDHL Global Mail International (Deprecated)
dicomDicom
direct_freightDirect Freight
direct_linkDirect Link
dominosDominos
doordashDoordash
doormanDoorman
dpdDPD
dpdukDPD UK
dxDX Delivery
dynamic_expressDynamic Express
ec_firstclassEC Firstclass
echo_global_logisticsEcho Global Logistics
ecmsECMS
ecom_expressEcom Express
econtEcont
eltaElta
epost_globalePost Global
essentialhubThe Essential Hub
estafetaEstafeta
estesEstes
evriEvri
express_cargoExpress Cargo Ltd
fan_courierFan Courier
fastwayFastway
fed_exFedEx (Deprecated)
fed_ex_mailviewFedEx Mailview (Deprecated)
fed_ex_same_day_cityFedEx SameDay City (Deprecated)
fed_ex_ukFedEx UK
fedexFedEx
fedex_smart_postFedEx SmartPost (Deprecated)
first_mileFirstMile
flashbirdFlashBird
flashboxFlashBox
flavor_cloudFlavorCloud
fleet_opticsFleet Optics
flexportFlexport
flock_freightFlock Freight
flyt_expressFlyt Express
freipostFreipost
fscfFrontier
g_globalG-Global Logistics
geisGEIS
gfsGlobal Freight Solutions
global_eGlobal-E
global_postGlobal Post
globegisticsGlobegistics
glovalinkGlova Link
glsGLS
go_peopleGo People
gofoGOFO
gsoGSO
hermesHermes
high_energy_transportHigh Energy Transport
hong_kong_postHong Kong Post
huahanHUAHAN Logistics
icsICS Courier
in_postInPost
india_postIndia Post
intelcomIntelcom Express
interlink_expressInterlink Express
international_bridgeInternational Bridge
israel_postIsrael Post
janco_freightJanco Freight
jiehangJiehang
jitsuJitsu
jiufangJiufang
jp_postJP Post
js_expressJS Express
kuroneko_yamatoKuroneko Yamato
la_posteLa Poste
landmark_globalLandmark Global
laser_shipLaserShip
latvijas_pastsLatvijas Pasts
lieferyLiefery
loomis_expressLoomis Express
lsoLSO
nanjing_woyuanNanjing Woyuan
network4Network4
newgisticsNewgistics
ninja_vanNinja Van
norcoNorco
nova_poshtaNova Poshta
nz_postNZ Post
ocs_worldwideOCS Worldwide
on_tracOnTrac
on_trac_direct_postOnTrac DirectPost
orange_dsOrange DS
osm_worldwideOsm Worldwide
pace_couriersPace Couriers
parcelforceParcelforce
parcllPARCLL
passportPassport
pcfPCF
pilotPilot
pitney_bowesPitney Bowes
pos_malaysiaPOS Malaysia
post_nlPostNL
post_nordPostNord
postenPosten
postmatesPostmates
pro_carrierPro Carrier
purolatorPurolator
rivoRivo
rl_carriersR+L Carriers
road_runnerRoadrunner
royal_mailRoyal Mail
rr_donnelleyRR Donnelley
rslRakuten Super Logistics
saiaSaia Motor Freight Line
sekoSeko
sendleSendle
sf_expressSF Express
sfcSFC
shanghai_shouwuShanghai Shouwu
shipbobShipBob
shipmonkShipmonk
singapore_postSingapore Post
skipSkip
smsa_expressSMSA Express
spee_deeSpee-Dee
speedxSpeedX
spring_gdsSpring GDS
sprint_shipSprintShip
stallion_expressStallion Express
star_trackStarTrack
starlinkStarlink
store_to_doorStore to Door
sunyouSunYou Logistics
swaySway
t_forceTForce
taiwan_postTaiwan Post
tntTNT
tollToll
toptransTopTrans
topyouTopYou
trexityTrexity
truckloadTruckload
tuffnellsTuffnells
ubi_smart_parcelUBI Smart Parcel
udsUDS
ukrposhtaUkrposhta
unisrsUNIS
uniuniUniUni
upsUPS
ups_iparcelUPS i-parcel (Deprecated)
ups_mail_innovationsUPS Mail Innovations
urgent_couriersUrgent Couriers
usf_hollandUSF Holland
uspsUSPS
vehoVeho
vitranVitran
wanb_expressWanbExpress
watkins_and_shepardWatkins And Shepard
whistlWhistl
wizmoWizmo
wn_directwnDirect
x_deliveryX Delivery
xdpXDP
xpoXPO
yanwenYanwen
ydhYDH
yellow_freightYellow Freight
yodelYodel
yun_expressYun Express
Body Params
json
Defaults to { "account_id": "123456789", "service_code": "S1", "origin": { "name": "Joe Santiego", "street1": "444 Castro St", "street2": "Suite 1200", "city": "Mountain view", "zip": "94041", "country": "US", "state": "CA", "email": "[email protected]", "phone": "+18978678653", "company": "Fulfil.IO Inc.", "validation_status": null, "address_type": null, "tax_identification": null }, "destination": { "name": "Joe Santiego", "street1": "444 Castro St", "street2": "Suite 1200", "city": "Mountain view", "zip": "94041", "country": "US", "state": "CA", "email": "[email protected]", "phone": "+18978678653", "company": "Fulfil.IO Inc.", "validation_status": null, "address_type": null, "tax_identification": null }, "packages": [ { "length": 4, "width": 4, "height": 5, "dimension_unit": "in", "weight": 7, "weight_unit": "lb", "carrier_code": null, "machinable": false, "dhl_ecommerce_dangerous_goods_category": null, "easyship_category": null, "description": "Merchandise", "quantity": null, "amount": null, "reference": null } ], "customs": { "customs_certify": true, "contents_type": "other", "customs_signer": null, "contents_explanation": "Electronic Items", "non_delivery_option": "return", "items": [ { "description": "iPhone 7", "quantity": 1, "value": 99, "currency": "USD", "company_currency": "EUR", "value_in_company_currency": 84, "weight": 1, "weight_unit": "lb", "hs_code": null, "sku": null, "country_of_origin": "US", "_options": {} }, { "description": "MacBook Pro", "quantity": 2, "value": 40, "company_currency": "EUR", "value_in_company_currency": 35, "currency": "USD", "weight": 6, "weight_unit": "lb", "hs_code": null, "sku": null, "country_of_origin": "US", "_options": {} } ], "incoterm": null, "invoice_number": null, "eel": null, "pfc": null, "exporter_tax_id_type": null, "exporter_tax_id": null, "exporter_eori_number": null, "importer": null }, "customer": { "email": "[email protected]" }, "options": { "reference1": "ORD1", "reference2": "SHP1", "is_return": false, "request_confirmation": "signature", "insurance_amount": "123.99" } }
Response

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json