Providing label

POST https://your-endpoint.com/label

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

JSON

{
  "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": "[phone]",
    "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": "[phone]",
    "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,
        "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,
        "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",
    "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
• packages[].label - Base 64 encoded PNG labels

JSON

{
  "tracking_number": "12345",
  "amount": "120.00",
  "packages": [{
      "label": "iVBORw0KGgoAAAANSUhEUgAAAaYAAAJ6CAYAAAB"
  }]
}

A fully detailed response can include

JSON

{
  "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 identifier	Carrier Name
ab_courrier	A&B Courier
abf	ABF
aci	ACI
ag_systems	Associated Global Systems
amazon_logistics	Amazon Logistics
amazon_mws	AmazonMws
apc	APC
apg	APG
aramex	Aramex
arrow_xl	ArrowXL
asendia	Asendia
asendia_hk	Asendia HK
asl	ASL Distribution
australia_post	Australia Post
axlehire_v3	AxlehireV3
better_trucks	Better Trucks
blue_dart	Bluedart
bni	Brunswick News
bopg	Bolt Delivery
boxberry	Boxberry
boxc	BoxC
cainiao	Cainiao
canada_post	Canada Post
canpar	Canpar
cdl	CDL Delivers
ceva	CEVA
china_ems	EMS
china_post	China Post
chronopost	Chronopost
cirro	CIRRO: Global E-Commerce Logistics
colis_prive	Colis Prive
colissimo	Colissimo
columbus_last_mile	CDL Last Mile Solutions
correios	Correios
correos_chile	Correos Chile
correos_costa_rica	Correos Costa Rica
couriers_please	CouriersPlease
dai_post	Dai Post
daylight_transport	Daylight Transport
delhivery	Delhivery
deliv	Deliv
deliverr	Deliverr
deutsche_post	Deutsche Post
dhl_ecommerce	DHL eCommerce
dhl_ecommerce_asia	DHL eCommerce Asia
dhl_express	DHL Express
dhl_freight	DHL Freight
dhl_germany	DHL Germany
dicom	Dicom
direct_freight	Direct Freight
direct_link	Direct Link
dominos	Dominos
doordash	Doordash
doorman	Doorman
dpd	DPD
dpduk	DPD UK
dx	DX Delivery
ec_firstclass	EC Firstclass
ecom_express	Ecom Express
estafeta	Estafeta
estes	Estes
evri	Evri
fastway	Fastway
fed_ex_mailview	FedEx Mailview
fed_ex_same_day_city	FedEx SameDay City
fed_ex_uk	FedEx UK
fedex	FedEx
fedex_smart_post	FedEx SmartPost
first_mile	FirstMile
flashbird	FlashBird
flashbox	FlashBox
flavor_cloud	FlavorCloud
fleet_optics	Fleet Optics
flexport	Flexport
flyt_express	Flyt Express
freipost	Freipost
fscf	Frontier
gfs	Global Freight Solutions
global_e	Global-E
global_post	Global Post
globegistics	Globegistics
gls	GLS
go_people	Go People
gso	GSO
hermes	Hermes
high_energy_transport	High Energy Transport
hong_kong_post	Hong Kong Post
ics	ICS Courier
india_post	India Post
intelcom	Intelcom Express
interlink_express	Interlink Express
international_bridge	International Bridge
israel_post	Israel Post
janco_freight	Janco Freight
jitsu	Jitsu
jp_post	JP Post
kuroneko_yamato	Kuroneko Yamato
la_poste	La Poste
landmark_global	Landmark Global
laser_ship	LaserShip
latvijas_pasts	Latvijas Pasts
liefery	Liefery
loomis_express	Loomis Express
lso	LSO
nanjing_woyuan	Nanjing Woyuan
network4	Network4
newgistics	Newgistics
ninja_van	Ninja Van
norco	Norco
nova_poshta	Nova Poshta
nz_post	NZ Post
ocs_worldwide	OCS Worldwide
on_trac	OnTrac
on_trac_direct_post	OnTrac DirectPost
orange_ds	Orange DS
osm_worldwide	Osm Worldwide
parcelforce	Parcelforce
parcll	PARCLL
passport	Passport
pcf	PCF
pilot	Pilot
pitney_bowes	Pitney Bowes
pos_malaysia	POS Malaysia
post_nl	PostNL
post_nord	PostNord
posten	Posten
postmates	Postmates
pro_carrier	Pro Carrier
purolator	Purolator
rivo	Rivo
rl_carriers	R+L Carriers
royal_mail	Royal Mail
rr_donnelley	RR Donnelley
rsl	Rakuten Super Logistics
seko	Seko
sendle	Sendle
sf_express	SF Express
shipmonk	Shipmonk
singapore_post	Singapore Post
skip	Skip
smsa_express	SMSA Express
spee_dee	Spee-Dee
sprint_ship	SprintShip
stallion_express	Stallion Express
star_track	StarTrack
starlink	Starlink
store_to_door	Store to Door
sunyou	SunYou Logistics
t_force	TForce
taiwan_post	Taiwan Post
tnt	TNT
toll	Toll
trexity	Trexity
truckload	Truckload
tuffnells	Tuffnells
ubi_smart_parcel	UBI Smart Parcel
uds	UDS
ukrposhta	Ukrposhta
unisrs	UNIS
uniuni	UniUni
ups	UPS
ups_iparcel	UPS i-parcel
ups_mail_innovations	UPS Mail Innovations
usf_holland	USF Holland
usps	USPS
veho	Veho
watkins_and_shepard	Watkins And Shepard
whistl	Whistl
wizmo	Wizmo
wn_direct	wnDirect
x_delivery	X Delivery
xdp	XDP
yanwen	Yanwen
yellow_freight	Yellow Freight
yodel	Yodel
yun_express	Yun Express