Mark customer shipments as shipped

curl --location --request PUT 'https://{merchant}.fulfil.io/services/3pl/v1/customer-shipments/ship.json' \
--data-raw '{
    "shipments": [
        {
            "id": 1,
            "carrier_identifier": "ups",
            "warehouse": 5, // only send if multi-warehouse setup in Fulfil for 3PL
            "tracking_number": "1Z012457878787",
            "cost": "10.59",
            "lines": [
            	{
            		"product_code": "SKU",
            		"quantity": 1.0
            	},
           		{
            		"product_code": "SKU",
            		"quantity": 1.0,
           			"lot": {
                		"number": "LOT-1"
            		}
            	}
            ]
        }
    ]
}'

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
fedex	FedEx
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
shipbob	ShipBob
shipmonk	Shipmonk
singapore_post	Singapore Post
skip	Skip
smsa_express	SMSA Express
spee_dee	Spee-Dee
speedx	SpeedX
sprint_ship	SprintShip
spring_gds	Spring Global Delivery Solutions
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_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

Sending a tracking URL

It is recommended to always include thetracking_urlin the shipment confirmation payload, as that will then be exported to external channels.

curl --location --request PUT 'https://{merchant}.fulfil.io/services/3pl/v1/customer-shipments/ship.json' \
--data-raw '{
    "shipments": [
        {
            "id": 97589,
            "carrier": "3pl",
            "carrier_service": "test_carrier_service1",
            "tracking_number": "TEST1079197",
            "tracking_url": "https://www.test-carrier.com/business-shipment-tracking/TEST1079197",
            "cost": "10.59",
            "lines": [
                {
                    "product_code": "ITEM-1",
                    "quantity": 2
                }
            ]
        }
    ]
}'

Marking bundled items as fulfilled

Fulfil natively supports the ability for merchants to sell and fulfil bundles. It is important the 3PL understand how this workflow works in Fulfil and how to handle fulfilling bundle components as sub-items in a customer shipment.

🚧
Important points to note

Fulfil will only mark the bundled item as shipped once all the bundle inputs have been fulfilled.

If partially fulfilling bundle inputs, the inputs fulfilled will be packaged separately with a unique tracking number - if included on the partial shipment confirmation.

Workflow overview

Customer purchases bundle item on sales channel.
Bundle item appears as a single line item on sales channel.
Bundle item appears as a single line item on Fulfil order.
The customer shipment line includes sub-items (sublines) identified from the BOM for components
3PL fetches the shipment information with the sub-items as components (see example payload below)
3PL sends shipping notification to indicate completion of shipment
Order line with bundle item is considered fulfilled if all inputs are fulfilled and tracking information is sent to sales channel.

"lines": [
                {
                    "currency": "USD",
                    "id": 674,
                    "order": {
                        "channel": {
                            "code": null,
                            "id": 2,
                            "name": "Phone Order"
                        },
                        "id": 277,
                        "number": "SO246",
                        "reference": null
                    },
                    "product": {
                        "code": "HOODIE-BUNDLE",
                        "id": 45,
                        "name": "Hoodie Bundle (Large & Medium)",
                        "upc": null
                    },
                    "quantity": 3.0,
                    "sublines": [
                        {
                            "id": 677,
                            "product": {
                                "code": "HOODIE-001-M",
                                "id": 8,
                                "name": "Hoodie (Medium)",
                                "upc": null
                            },
                            "quantity": 3.0,
                            "uom": "u"
                        },
                        {
                            "id": 676,
                            "product": {
                                "code": "HOODIE-001-L",
                                "id": 7,
                                "name": "Hoodie (Large)",
                                "upc": null
                            },
                            "quantity": 3.0,
                            "uom": "u"
                        }
                    ],
                    "unit_customs_value": {
                        "__class__": "Decimal",
                        "decimal": "91.95"
                    },
                    "unit_price": {
                        "__class__": "Decimal",
                        "decimal": "91.95"
                    },
                    "uom": "u"
                }
            ]

Sending consumable inventory consumption

The 3PL API supports tracking consumption of packaging materials (such as boxes, bubble wrap, or other consumables) used during the fulfillment process. This allows Fulfil to automatically adjust inventory levels for these consumable items.

To report consumable usage, include them in the items[] array within each package, just like regular products. The key difference is that these items must be configured as consumables in Fulfil before they can be tracked this way.

JSON

{
    "shipments": [
        {
            "id": 538,
            "carrier_identifier": "ups",
            "tracking_number": "1Z9999999999999988",
            "cost": "23.89",
            "packages": [
                {
                    "reference": "PKG11",
                    "dimensions": {
                        "length": 10,
                        "width": 10,
                        "height": 10,
                        "uom": "in"
                    },
                    "medium": "CTN",
                    "material": "05",
                    "weight": 10.0,
                    "weight_uom": "lb",
                    "tracking_number": "1Z9999999999999999",
                    "carrier_identifier": "ups",
                    "items": [
                { "product_code": "SHIRT-BLK-M", "quantity": 2 }
            ],
            "consumables": [
                { "product_code": "BOX-12X12X12", "quantity": 1 },
                { "product_code": "BUBBLE-WRAP-SM", "quantity": 1 }
            ]
                }
            ]
        }
    ]
}

In the example above, BOX-12X12X12 and BUBBLE-WRAP-SM are configured as consumables in Fulfil. When this shipment is marked as shipped, Fulfil will:

Fulfill the 2 units of SHIRT-BLK-M as a regular product shipment
Consume 1 unit of BOX-12X12X12 from consumable inventory
Consume 1 unit of BUBBLE-WRAP-SM from consumable inventory

Important notes:

Consumable items must be pre-configured in Fulfil with the consumable flag enabled
If a product code is not configured as a consumable, Fulfil will treat it as a regular item and throw an error since that item is not part of the original order

Supported carrier identifiers

Sending a tracking URL

Marking bundled items as fulfilled

🚧Important points to note

Workflow overview

Sending consumable inventory consumption

🚧
Important points to note