| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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 numberamount- The total shipping cost that will be charged to the merchantcurrency- 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:
- Multiple packages in a single shipment need individual labels
- Each package might need to be retried independently
- 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:
- PNG
- When using "PNG" as the label type, the PNG label content should be provided in Base64 encoded format.
- 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 |
|---|---|
| 4px | 4PX |
| aaa_cooper | AAA Cooper Transportation |
| 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 |
| brinks_global | Brinks Global Services USA |
| brt | BRT |
| cainiao | Cainiao |
| canada_post | Canada Post |
| canpar | Canpar |
| cargors | Cargors Pallet Carrier |
| cargus | Cargus |
| cdl | CDL Delivers |
| central_transport | Central Transport |
| ceva | CEVA |
| china_ems | EMS |
| china_post | China Post |
| chronopost | Chronopost |
| cirro | CIRRO: Global E-Commerce Logistics |
| cityx | City Logistics Transport |
| cne_express | CNE Express |
| 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 |
| cte | California Transportation Enterprises |
| dachser | Dachser |
| 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 |
| dhl_global_mail | DHL Global Mail (Deprecated) |
| dhl_globalmail_international | DHL Global Mail International (Deprecated) |
| dicom | Dicom |
| direct_freight | Direct Freight |
| direct_link | Direct Link |
| dominos | Dominos |
| doordash | Doordash |
| doorman | Doorman |
| dpd | DPD |
| dpduk | DPD UK |
| dx | DX Delivery |
| dynamic_express | Dynamic Express |
| ec_firstclass | EC Firstclass |
| echo_global_logistics | Echo Global Logistics |
| ecms | ECMS |
| ecom_express | Ecom Express |
| econt | Econt |
| elta | Elta |
| epost_global | ePost Global |
| essentialhub | The Essential Hub |
| estafeta | Estafeta |
| estes | Estes |
| evri | Evri |
| express_cargo | Express Cargo Ltd |
| fan_courier | Fan Courier |
| fastway | Fastway |
| fed_ex | FedEx (Deprecated) |
| fed_ex_mailview | FedEx Mailview (Deprecated) |
| fed_ex_same_day_city | FedEx SameDay City (Deprecated) |
| fed_ex_uk | FedEx UK |
| fedex | FedEx |
| fedex_smart_post | FedEx SmartPost (Deprecated) |
| first_mile | FirstMile |
| flashbird | FlashBird |
| flashbox | FlashBox |
| flavor_cloud | FlavorCloud |
| fleet_optics | Fleet Optics |
| flexport | Flexport |
| flock_freight | Flock Freight |
| flyt_express | Flyt Express |
| freipost | Freipost |
| fscf | Frontier |
| g_global | G-Global Logistics |
| geis | GEIS |
| gfs | Global Freight Solutions |
| global_e | Global-E |
| global_post | Global Post |
| globegistics | Globegistics |
| glovalink | Glova Link |
| gls | GLS |
| go_people | Go People |
| gofo | GOFO |
| gso | GSO |
| hermes | Hermes |
| high_energy_transport | High Energy Transport |
| hong_kong_post | Hong Kong Post |
| huahan | HUAHAN Logistics |
| ics | ICS Courier |
| in_post | InPost |
| india_post | India Post |
| intelcom | Intelcom Express |
| interlink_express | Interlink Express |
| international_bridge | International Bridge |
| israel_post | Israel Post |
| janco_freight | Janco Freight |
| jiehang | Jiehang |
| jitsu | Jitsu |
| jiufang | Jiufang |
| jp_post | JP Post |
| js_express | JS Express |
| 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 |
| pace_couriers | Pace Couriers |
| 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 |
| road_runner | Roadrunner |
| royal_mail | Royal Mail |
| rr_donnelley | RR Donnelley |
| rsl | Rakuten Super Logistics |
| saia | Saia Motor Freight Line |
| seko | Seko |
| sendle | Sendle |
| sf_express | SF Express |
| sfc | SFC |
| shanghai_shouwu | Shanghai Shouwu |
| shipbob | ShipBob |
| shipmonk | Shipmonk |
| singapore_post | Singapore Post |
| skip | Skip |
| smsa_express | SMSA Express |
| spee_dee | Spee-Dee |
| speedx | SpeedX |
| spring_gds | Spring GDS |
| sprint_ship | SprintShip |
| stallion_express | Stallion Express |
| star_track | StarTrack |
| starlink | Starlink |
| store_to_door | Store to Door |
| sunyou | SunYou Logistics |
| sway | Sway |
| t_force | TForce |
| taiwan_post | Taiwan Post |
| tnt | TNT |
| toll | Toll |
| toptrans | TopTrans |
| topyou | TopYou |
| 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 (Deprecated) |
| ups_mail_innovations | UPS Mail Innovations |
| urgent_couriers | Urgent Couriers |
| usf_holland | USF Holland |
| usps | USPS |
| veho | Veho |
| vitran | Vitran |
| wanb_express | WanbExpress |
| watkins_and_shepard | Watkins And Shepard |
| whistl | Whistl |
| wizmo | Wizmo |
| wn_direct | wnDirect |
| x_delivery | X Delivery |
| xdp | XDP |
| xpo | XPO |
| yanwen | Yanwen |
| ydh | YDH |
| yellow_freight | Yellow Freight |
| yodel | Yodel |
| yun_express | Yun Express |
