Fulfill and ship orders
Once an order is paid, your warehouse, store, or team gets the goods to the buyer, and Flint records how. A fulfillment covers some quantity of the order's line items and says how they reach the buyer. You report each step. Flint keeps the fulfillment's status, the order's fulfillment_status, the stock ledger, and the buyer's shipping emails in step with what you report.
Flint doesn't buy labels or track carriers. Your shipping software or carrier integration reports package progress, and Flint emails the buyer at each moment that matters. To set up the delivery methods and rates the buyer picks at checkout, see Add shipping to a checkout. Every field is in the Fulfillment API reference.
- Flint sends fulfillment.created, shortly after payment to Your server
- Your server sends mark_picked or mark_packed (optional) to Flint
- Your server sends POST /v1/shipments with shipped packages to Flint
- Flint sends shipped email for each package, with tracking to Buyer
- Flint sends fulfillment.updated, status dispatched to Your server
- Your server sends mark_delivered on each package to Flint
- Flint sends delivered email for each package to Buyer
- Flint sends fulfillment.completed to Your server
How a fulfillment is organized#
Each fulfillment has a type, which decides the steps it accepts and when its stock leaves on hand:
type | Steps you send | Stock leaves on hand at |
|---|---|---|
shipment | accept, mark_picked, mark_packed, then package actions | dispatch, or complete if it skips dispatch |
local_delivery | accept, mark_preparing, dispatch, complete | dispatch, or complete if it skips dispatch |
pickup | accept, mark_preparing, mark_ready, complete | complete |
digital | accept, complete | complete |
service | accept, schedule, start, complete | complete |
Every step is optional. A fulfillment can go straight from pending to the last step when you have nothing to report in between.
A shipment-type fulfillment holds one or more shipments, one per carrier leg. Each shipment holds packages, one per parcel. Tracking lives on the package, and package items record which order line quantities are in each box. The shipment has no actions of its own: its status comes from its packages, where an exception outranks everything else and otherwise the least advanced package sets the pace.
Flint also keeps two logs for each fulfillment. Fulfillment events are its timeline: status changes, tracking changes, and carrier scans. Fulfillment notifications record every buyer email Flint sent or skipped.
1. Find the work#
Fulfillments Flint creates#
When an order is paid with a delivery choice (shipping, pickup, or local delivery), Flint creates its fulfillments shortly after payment, once all of the units it covers are in stock (see Automatic creation waits for stock): one for each execution leg of the delivery the buyer chose. Each starts at pending, and Flint sends fulfillment.created for each one. Start your delivery work from that event and use those fulfillments. This applies whether the buyer chose at checkout or your backend selected the delivery and paid.
A carry-out order with a handover has no delivery choice. When it is paid, Flint creates one handover fulfillment at the handover location, already completed. You receive fulfillment.created and fulfillment.completed, and there's nothing left to fulfill.
To list an order's fulfillments:
curl "https://api.withflintpay.com/v1/fulfillments?order_id=ord_1kmn0aExample" \
-H "Authorization: Bearer YOUR_API_KEY"
fulfillment.created is the signal to act on. A handler that reacts to order.paid instead can find this list still empty, because creation runs after payment. Don't create a fulfillment of your own for quantities Flint has already created fulfillments for. While Flint is still creating them, that returns 409 OPERATION_IN_PROGRESS with details[0].reason: delivery_selection_materializing; afterward, it returns 409 ACTION_NOT_ALLOWED.
Flint never creates digital or service fulfillments. You create one for a line whose fulfillment requirement is required with resolution_mode: "manual" and the fulfillment's type in allowed_types. A custom line sets that in its fulfillment. A catalog line gets it from a manual delivery profile you assign to the variant of a digital or service product, with allowed_types exactly ["digital"] or ["service"] to match product_type. See Create a fulfillment yourself.
A catalog digital or service variant with no profile, and a custom line with requirement: "none", has nothing to fulfill: the order's fulfillment_status is not_applicable, and creating a fulfillment for the line returns 400 INVALID_REQUEST with detail code NOT_ALLOWED at line_items[i].order_line_item_id. Deliver those from your own app after order.paid and a check of the order's dispute_status (access rules); that remains a valid setup. A profile applies to orders created after you assign it. Existing orders retain their fulfillment requirements.
Automatic creation waits for stock#
Flint creates the fulfillments for a delivery choice only when all of the remaining units are in stock. Units on backorder aren't in stock yet, so an order that has some waits, and Flint doesn't split its delivery choice into shipments on its own. Until the last remaining unit is in stock, no fulfillment appears from the selection.
The remaining units are the selected quantity minus the quantity already assigned to fulfillments, including fulfillments you created yourself, and minus units removed from the order by an order edit. For example, with 3 units selected, 1 assigned to a fulfillment you created, and 1 removed, 1 unit remains. To ship the units you have sooner, create a fulfillment yourself for them. You can fulfill each line's unassigned_quantity minus its backordered_quantity. When the rest is in stock, Flint creates fulfillments for the remainder only. If every unit has been assigned or removed by then, it creates nothing.
Work from queues#
To work from a list instead of reacting to each event, filter by state. GET /v1/fulfillments takes status, type, location_id, and order_id. Repeat status or type, or separate values with commas, to match any of them. To work through a schedule, add sort_by=scheduled_start_at&sort_direction=asc. scheduled_start_at is the start of the pickup, local delivery, or shipment window, or the service appointment, and is null for digital and unbooked fulfillments.
For a packing list, fetch a page of GET /v1/fulfillments?status=pending&type=shipment&page_size=100, then collect its distinct order_id values. Fetch all those orders with one GET /v1/orders request, repeating order_id or separating IDs with commas:
curl "https://api.withflintpay.com/v1/orders?order_id=ord_1kmn0aExample,ord_2kmn0aExample&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
The order list returns full orders, including line_items, subscription_id, subscription_cycle, and subscription_delivery_number. Join fulfillment lines to order lines by order_id and order_line_item_id for the name, SKU, variant_id, and selected_options. For bundles, match bundle_component_id to the order line's bundle_components to identify the component; use the fulfillment line's quantity for how many to pack. Use the fulfillment's recipient for the destination. For a subscription's first-box insert, check subscription_cycle == 1 and that subscription_delivery_number is null, since later prepaid boxes in that cycle have delivery numbers starting at 2.
This takes two list requests per queue page instead of an order read per box. The order filter accepts up to 100 distinct IDs. Keep that ID set while following an order next_page_token, and follow the fulfillment queue's next_page_token for the next batch. Unknown orders and orders outside the API key's merchant or environment are omitted; leave those rows unresolved instead of packing them from incomplete details. expand=order returns a summary, which does not include the packing fields.
Once shipments exist, list them by state. This lists outbound shipments that are packed and waiting for the carrier:
curl "https://api.withflintpay.com/v1/shipments?direction=outbound&status=packed&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
status=exception,delivery_attempted finds shipments that need attention. To find the package behind a carrier scan, send its carrier and tracking number. Both match the whole stored value exactly, and tracking numbers can repeat across carriers, so send both:
curl "https://api.withflintpay.com/v1/packages?carrier=ups&tracking_number=1Z999AA10123456784" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": [
{
"package_id": "pkg_1kmn0aExample",
"shipment_id": "shp_1kmn0aExample",
"fulfillment_id": "ful_1kmn0aExample",
"order_id": "ord_1kmn0aExample",
"status": "shipped",
"carrier": "ups",
"tracking_number": "1Z999AA10123456784",
"shipped_at": "2026-09-22T16:05:00Z"
}
],
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}
This example leaves out most package fields. With no next_page_token, it is the last page. When you page, send the same filters with each page_token; a token works only with the filters it was issued for. List shipments and packages has every filter, including updated_after, handed_off_after, and partial matching with query. Add expand=order to any of these lists to get each row's order beside it.
Find orders that still need a fulfillment#
To find paid orders with quantity that no fulfillment owns, such as digital lines or units handed back by a failed fulfillment:
curl "https://api.withflintpay.com/v1/orders?payment_status=paid&has_unassigned_fulfillment_quantity=true" \
-H "Authorization: Bearer YOUR_API_KEY"
Each line item carries fulfillment_quantities. Its unassigned_quantity is what you can put into a new fulfillment. An order leaves this list once no unassigned quantity is left, because fulfillments own it or it was removed from the order, and comes back when a fulfillment fails with release_quantity: true. A shipping, pickup, or local delivery order also appears here until Flint creates its fulfillments, which is a moment after payment, or later when units are still on backorder, so check the order's fulfillments before you create one. See Filter orders by unassigned quantity. Unassigned quantity can include units that are still on backorder and can't ship yet: Create a fulfillment yourself says how much you can fulfill, and has_backordered_quantity=true lists the orders waiting on stock.
2. Prepare the order#
Every fulfillment lists the actions it accepts right now in supported_actions. Each value names one route under /v1/fulfillments/{fulfillment_id}/, with underscores written as hyphens: mark_packed is /mark-packed and release_hold is /release-hold. The routes are accept, schedule, start, mark-preparing, mark-picked, mark-packed, mark-ready, dispatch, complete, mark-no-show, fail, cancel, hold, and release-hold.
curl -X POST https://api.withflintpay.com/v1/fulfillments/ful_1kmn0aExample/mark-packed \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ful_1kmn0aExample-packed" \
-H "Content-Type: application/json" \
-d '{ "expected_version": 2 }'
{
"data": {
"fulfillment_id": "ful_1kmn0aExample",
"order_id": "ord_1kmn0aExample",
"type": "shipment",
"status": "packed",
"version": 3,
"picked_at": "2026-09-22T14:30:00Z",
"packed_at": "2026-09-22T15:10:00Z",
"supported_actions": ["dispatch", "complete", "cancel", "fail", "hold"]
},
"request_id": "req_01KWM6S28J37K3GFF9QRM8YWA4"
}
The response is the updated fulfillment; this example leaves out most of its fields. It doesn't include the timeline event or email records the action created. Read those as in Read events and notifications.
- Send
expected_version. It must match the fulfillment'sversion. A stale value returns409 VERSION_CONFLICTand changes nothing. - Each route takes only its own fields, and no
action.holdneeds areason,scheduleneedsscheduled_start_atandscheduled_end_at,failneedsrelease_quantity, andmark-no-showneeds areason. Every route acceptsoccurred_atfor when it happened andreason_message, an internal note of up to 500 characters. Flint keeps this note out of buyer emails. - Retry with the same
Idempotency-Keyand body. A replay returns the original result without another email. See Idempotency. supported_actionsfollows the fulfillment, not your credential. It is[]while the order isn't paid, because Flint refuses every action until payment. Your credential still needs permission to call the route.
Until dispatch, every type also accepts hold and fail, and cancel while it has no shipment that isn't voided. A service also accepts mark_no_show. A dispatched fulfillment accepts only complete and fail.
Fulfillment status#
status reports exactly where the fulfillment is. Each type uses the values its steps reach. Filter GET /v1/fulfillments by any of them.
status on fulfillmentactive_hold is present exactly when status is on_hold, and outcome exactly when it is no_show. terminal_at records when the fulfillment reached a terminal status.
Hold and release#
hold pauses the fulfillment at on_hold with a reason, such as address_issue or customer_request. Your reason_message appears as active_hold.reason_notes:
curl -X POST https://api.withflintpay.com/v1/fulfillments/ful_1kmn0aExample/hold \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ful_1kmn0aExample-hold-1" \
-H "Content-Type: application/json" \
-d '{ "reason": "address_issue", "reason_message": "Confirming the apartment number", "expected_version": 3 }'
active_hold.initiated_by is merchant when you or your integration placed the hold, or flint when Flint placed a payment hold. This read-only field identifies who paused the work. Merchant holds block package-derived progress whatever their reason, including legacy holds with reason payment_review.
payment_review is reserved for Flint. Sending it as the reason for a merchant hold returns 400 INVALID_REQUEST with detail INVALID_VALUE at reason. Use fraud_review for your own review, or other with reason_message.
active_hold.previous_status records the status the hold paused, which is never on_hold or terminal. A held fulfillment can only move forward from there:
release_holdreturns it toprevious_status. It keeps the schedule and progress timestamps such aspicked_atandpacked_at, never emails the buyer, and rejectsbuyer_notification_behavior.- Any other action that
previous_statusallows, excepthold, moves it on and clears the hold. A fulfillment held atpackedacceptsdispatchbut notmark_picked.
supported_actions lists exactly these exits. Holds are private to the merchant: buyer responses under /v1/me show a held fulfillment at its previous_status with no active_hold, and putting work on hold sends no email.
Require approval#
When the merchant turns on fulfillment.approval_required in settings, a new fulfillment offers only accept, hold, cancel, and fail until someone accepts it. A fulfillment held before acceptance also offers release_hold.
3. Ship the packages#
For a shipment-type fulfillment, create its shipment with one package per box. Give each package its contents and tracking, and status: shipped to report the carrier handoff in the same call:
curl -X POST https://api.withflintpay.com/v1/shipments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: shipment-1042" \
-H "Content-Type: application/json" \
-d '{
"fulfillment_id": "ful_1kmn0aExample",
"direction": "outbound",
"packages": [
{
"status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456784",
"items": [
{ "order_line_item_id": "li_1kmn0aExampleA", "quantity": 1 },
{ "order_line_item_id": "li_1kmn0aExampleB", "quantity": 1 }
]
},
{
"status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456785",
"items": [{ "order_line_item_id": "li_1kmn0aExampleC", "quantity": 1 }]
}
]
}'
{
"data": {
"shipment_id": "shp_1kmn0aExample",
"fulfillment_id": "ful_1kmn0aExample",
"order_id": "ord_1kmn0aExample",
"direction": "outbound",
"status": "shipped",
"package_count": 2,
"shipped_at": "2026-09-22T16:05:00Z",
"handed_off_at": "2026-09-22T16:05:00Z",
"packages": [
{ "package_id": "pkg_1kmn0aExample", "status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456784" },
{ "package_id": "pkg_1kmn0aExampleB", "status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456785" }
]
},
"request_id": "req_01KWM6H6EF3N5C3ZK19ZSFRE11"
}
These examples leave out most fields. The shipment, its packages and items, the timeline entries, the buyer emails, and any fulfillment progress commit together; a failure commits nothing. Because every unit is in a shipped box, this call also moves the fulfillment to dispatched, as described in How packages move the fulfillment.
- Send 1 to 20 packages. Each needs
status: createdorstatus: shipped. For a shipped package, send 1 to 100 entries initems, with each order line and bundle component at most once per box. To ship the entire fulfillment in one package, setpack_fulfillment_items: trueon the package and omititems. Omitting both returns400 INVALID_REQUESTwith detailREQUIREDat the package'sitemsfield. Across all packages, quantities can't exceed what the fulfillment covers for that component. - Check the fulfillment version. Send
expected_fulfillment_versionon the shipment or standalone package request to use the version you last read. If the fulfillment changed, Flint refuses the request with409 VERSION_CONFLICTbefore creating any shipping records. - Create labels before handoff. Send
status: created, thenmark_shippedon each package when the carrier takes it. To add a box later, usePOST /v1/packages. - Choose when to email. Each
shippedpackage sends one shipped email with its tracking link. Setbuyer_notification_behavior: suppresson a package to skip its email.shipped_atdefaults to the request time. Both fields are allowed only withshipped. - Retry with the same
Idempotency-Keyand body. A replay returns the original IDs and sends no second email.external_reference_idhelps you find a shipment later but doesn't prevent duplicates. - The delivery address is on the fulfillment.
recipientholds the address and buyer email copied from the order. If the buyer asks for a change, update it withPATCH /v1/fulfillments/{fulfillment_id}.
Return shipments carry goods back from the buyer and take no packages here; see Return labels and tracking.
Change a box's contents#
Package items include bundle_component_id, which is null for a non-bundle line. For a bundle, send the component ID from the order line's bundle_components; quantity counts component units. An explicit ID is required for every bundle-line create and PATCH, even when the fulfillment has only one component for that line. The same inputs work in inline packages on fulfillment and shipment creation, and on package-item create and PATCH. A package can hold separate rows for the same order line's different components.
Capacity is checked separately for each order line and component across active packages. Exceeding one component's quantity returns 409 LIMIT_EXCEEDED, even if another component has capacity. Missing IDs for bundle lines return 400 INVALID_REQUEST with detail REQUIRED; IDs outside the line return detail INVALID_VALUE, both at the item's bundle_component_id. With single_package fulfillment creation, Flint packs every requested component automatically.
Read a package's contents with GET /v1/packages/{package_id}/items. Each item has its own version. To change a quantity only if nobody changed the item since you read it, send that version as expected_version:
curl -X PATCH https://api.withflintpay.com/v1/packages/pkg_1kmn0aExample/items/pki_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: pkg-item-qty-pki_1kmn0aExample-1" \
-H "Content-Type: application/json" \
-d '{ "quantity": 2, "expected_version": 1 }'
DELETE /v1/packages/{package_id}/items/{package_item_id}?expected_version=1 removes an item the same way. A stale value returns 409 VERSION_CONFLICT and changes nothing. Contents, new packages, and voids are allowed only before handoff.
Correct tracking#
PATCH /v1/packages/{package_id} corrects tracking, carrier, service, label URL, weight, dimensions, expected delivery time, status reason, external references, or metadata. These fields stay editable after delivery and completion, until the package is voided. Send null to clear a field. PATCH /v1/shipments/{shipment_id} corrects a shipment's external references and metadata until it is voided. Corrections never email the buyer.
Void a mistake#
Before handoff, void what you created by mistake. POST /v1/packages/{package_id}/void and POST /v1/shipments/{shipment_id}/void work while the shipment is created or packed. Voiding a package returns the package. Voiding a shipment voids its packages too, so it returns both:
{
"data": {
"shipment": { "shipment_id": "shp_1kmn0aExample", "status": "voided" },
"packages": [{ "package_id": "pkg_1kmn0aExample", "status": "voided" }]
}
}
This example leaves out most fields. Voided packages and shipments no longer count toward the fulfillment's progress.
4. Report carrier progress#
As each parcel moves, send POST to the package action route named in supported_actions, with underscores replaced by hyphens. For example, mark_shipped names POST /v1/packages/{package_id}/mark-shipped. Send only the action fields in the body, without action. If a created or packed package has no items, attempts to record carrier progress return 409 ACTION_NOT_ALLOWED with reason package_empty. Add at least one item to the package and retry. For label-first work, mark_shipped records the handoff and can set the final tracking in the same request:
curl -X POST https://api.withflintpay.com/v1/packages/pkg_1kmn0aExample/mark-shipped \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: pkg_1kmn0aExample-shipped" \
-H "Content-Type: application/json" \
-d '{
"occurred_at": "2026-09-22T16:05:00Z",
"carrier": "ups",
"service_code": "ground",
"tracking_number": "1Z999AA10123456784",
"tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
}'
carrier, service_code, tracking_number, and tracking_url are accepted only on mark_shipped. Fields you send replace the package's values before the shipped email is built; fields you leave out stay unchanged. They can't be null here, so clear a field with PATCH. Send buyer_notification_behavior: suppress to record the handoff without emailing the buyer, or send send to request the shipped email. If you omit the field, Flint follows its default email rules. The response is the updated package.
| Route | Package status | Buyer email |
|---|---|---|
/mark-packed | packed | None |
/mark-shipped | shipped | Shipped, with the tracking link |
/mark-in-transit | in_transit | None |
/mark-out-for-delivery | out_for_delivery | Out for delivery |
/mark-delivery-attempted | delivery_attempted | Delivery attempted |
/mark-delivered | delivered | Delivered |
/mark-exception | exception | Delivery issue |
/mark-returned | returned | Returned to sender |
A package starts at created or shipped, and voiding it sets voided. Every action accepts occurred_at, reason_message, expected_version, and buyer_notification_behavior. Nothing in Flint moves a package on its own, in live mode or a sandbox, so your integration sends each step it learns from the carrier.
A shipped package can move to in_transit. Call /mark-in-transit again while it is in transit to refresh the estimate, or after out_for_delivery or delivery_attempted when it returns to a depot. A repeat changes the version and emits package.updated only when the estimate changes; it creates no status event or buyer notification.
For a return to in_transit from out_for_delivery or delivery_attempted, occurred_at must be at or after the package's latest recorded status time. An older scan returns 409 ACTION_NOT_ALLOWED with reason out_of_order; details[0].latest_status_occurred_at gives that time. The refused scan changes no resource or event.
Share an expected delivery time#
expected_delivery_at is when you or the carrier expect a package to arrive. Set it when you create the package, change it with PATCH /v1/packages/{package_id}, or send it with mark_shipped, mark_in_transit, or mark_out_for_delivery:
curl -X POST https://api.withflintpay.com/v1/packages/pkg_1kmn0aExample/mark-in-transit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: pkg_1kmn0aExample-in-transit-1" \
-H "Content-Type: application/json" \
-d '{
"occurred_at": "2026-09-23T09:40:00Z",
"expected_delivery_at": "2026-09-25T21:00:00Z"
}'
Leave it out to keep the current value, or send null to clear it. Past times are accepted, so a late parcel keeps its estimate as history, and the value stays on the package after delivery; hide it from buyer arrival estimates once the package is delivered. It belongs to one package and is separate from the fulfillment's promised shipping window, shipment_details.window_start_at and window_end_at.
Record a carrier scan#
A scan that changes no status, such as a departure from a sorting facility, goes to the fulfillment's timeline instead:
curl -X POST https://api.withflintpay.com/v1/fulfillment-events \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fulfillment_id": "ful_1kmn0aExample",
"event_type": "carrier_scan",
"package_id": "pkg_1kmn0aExample",
"external_system": "ups",
"external_event_id": "scan-88412",
"external_status": "Departed facility",
"location_description": "Louisville, KY",
"occurred_at": "2026-09-23T03:12:00Z"
}'
event_type is carrier_scan or custom. Add package_id or shipment_id to attach the entry to a box or a leg. Send external_system with external_event_id so a repeated scan is recorded once: the first returns 201 with the new event, and a repeat returns 200 with the same fulfillment_event_id. Reusing an external_event_id with different details returns 409 ALREADY_EXISTS with the recorded event in details[0].current_resource. These entries never email the buyer. Status changes such as shipped or delivered are package actions; sending one as an event_type returns 400 INVALID_REQUEST with param: event_type.
How packages move the fulfillment#
Once a shipment-type fulfillment has a package, its packages move it forward. Only packages that aren't voided, in outbound shipments that aren't voided, count:
- In progress once the first outbound package ships, while full dispatch is still pending.
- Dispatched once every unit of the fulfillment is in a package and every package has left with the carrier (
shippedor later).dispatched_atis the latest package'sshipped_at, and stock leaves on hand. - Completed once, with every unit packed, every package is
delivered.completed_atis the latest package'sdelivered_at, so a return window that starts at delivery counts from the carrier's delivery. The order'sfulfillment_statusupdates andfulfillment.completedfires. A package inexceptionorreturnedprevents automatic completion.
Each step happens in the same request as the package action that triggers it. That response is the package, so read the fulfillment or listen for fulfillment.updated and fulfillment.completed to see the step. Two packages delivered at the same moment complete the fulfillment once.
Packages don't move a fulfillment that is waiting for accept, that you put on hold (whatever the hold reason), or whose payment is holding fulfillment. The package still records its progress and emails the buyer. When the fulfillment can go on, send dispatch or complete yourself. On a held fulfillment, that also clears the hold.
Once completed, a fulfillment stays completed. A later package action, such as mark_returned after a return to sender, changes only the package and sends its own events and email. With packages, the delivery time comes only from them, so PATCH /v1/fulfillments/{fulfillment_id} with completed_at returns 409 ACTION_NOT_ALLOWED with details[0].reason: derived_from_packages.
5. Complete it#
With packages, delivery of the last package completes the fulfillment. Send complete yourself when nothing will report it: a pickup handed over, a local delivery dropped off, a digital or service order finished, a shipment you track without packages, or a parcel whose carrier never reports delivery.
curl -X POST https://api.withflintpay.com/v1/fulfillments/ful_1kmn0aExample/complete \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ful_1kmn0aExample-complete" \
-H "Content-Type: application/json" \
-d '{ "occurred_at": "2026-09-24T18:20:00Z" }'
occurred_at on complete becomes the fulfillment's completed_at, the delivery or handover time. Send it when you know it. For shipments, omitting it records the time you mark the shipment complete, so a return window that starts at delivery counts from that time. Other fulfillment types leave completed_at empty when you omit it. To correct the time on a shipment without packages, PATCH /v1/fulfillments/{fulfillment_id} with completed_at.
The order's fulfillment_status counts only completed fulfillments. It stays not_fulfilled through packing and dispatch, moves to partially_fulfilled when some quantity is complete, and reaches fulfilled when all of it is. Quantity removed from the paid order counts like canceled quantity: if all of it was canceled or removed, the order ends canceled, and if some was completed and the rest canceled or removed, it ends closed. An order with nothing to ship is not_applicable. The full list is in Statuses and supported actions.
Pickup, local delivery, digital, service, and handover#
- Pickup.
mark_readyemails the buyer that the order is waiting.completerecords the collection and takes the stock off hand. For a buyer who never comes, sendcancelorfail;mark_no_showis for services only.pickup_detailsnames the store, andrecipient.instructionsholds any note the buyer left for it. - Local delivery. Works like a shipment without shipments or packages:
dispatchwhen the courier leaves, which emails the buyer, thencompleteon delivery. Put the courier's link inlocal_delivery_details.tracking_url. - Digital. Only a line that requires a
digitalfulfillment gets one: a custom line with that requirement, or a catalog line whose variant has a manual profile withallowed_types["digital"]. Create it yourself after the order is paid. Put the download link indigital_details.delivery_urland sendcompleteonce the buyer has it. The completed email links the buyer to their order in their account rather than to the file. Once the buyer is refunded for what the fulfillment delivered, because the order is fully refunded or every line it covers is refunded in full, buyer reads under/v1/mereturndelivery_urlasnulland the account stops offering the download. A partial refund by amount keeps the link. Your own reads and webhooks still show the URL, and the URL itself keeps working, so use a link that expires or that your app checks, and end access in your app onorder.refundedororder.partially_refunded. A catalog digital variant with no profile gets no fulfillment, so deliver it from your app afterorder.paidand a check of the order'sdispute_status. - Service. Only a line that requires a
servicefulfillment gets one, from a custom line or a catalog variant with a manual profile withallowed_types["service"]. A service is fulfilled asservice, never asdigital.schedulebooks the appointment window,startmarks it underway, andmark_no_showrecords a missed appointment with areason, such ascustomer_no_show. - Handover. For a counter sale where the buyer leaves with the goods, set the order's
handoverinstead of a delivery choice. When the order is paid, Flint creates onehandoverfulfillment at the handover location and completes it in the same step, so it arrives alreadycompleted, withfulfillment.createdandfulfillment.completedand no buyer email. You can't create or advance ahandoverfulfillment yourself. A return works as for any completed fulfillment.
Set pickup_details.pickup_due_at for when the buyer should collect the order, or local_delivery_details.delivery_due_at for when it should arrive. Passing either deadline does not change the fulfillment status or send an event automatically. Review overdue work in your integration and decide whether to contact the buyer, complete, cancel, or fail the fulfillment.
Create a fulfillment yourself#
Create a fulfillment with POST /v1/fulfillments when no fulfillment covers the quantity: a line that requires a digital or service fulfillment, a custom line or a catalog line from a variant with a manual delivery profile, units a failed fulfillment handed back, or in-stock units of a delivery choice that Flint is holding until the rest arrive. The order must be paid, and the fulfillment's type must be in the line's allowed_types. Once created, a manual fulfillment moves through the same actions as any other, and complete finishes it. For a custom line created with "fulfillment": {"requirement": "required", "resolution_mode": "manual", "allowed_types": ["digital"]}, or a catalog line whose variant has a manual profile with allowed_types ["digital"]:
curl -X POST https://api.withflintpay.com/v1/fulfillments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-1042-ebook" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ord_1kmn0aExample",
"type": "digital",
"line_items": [{ "order_line_item_id": "li_1kmn0aExampleD", "bundle_component_id": null, "quantity": 1 }],
"digital_details": { "delivery_url": "https://downloads.example.com/orders/1042/guide.pdf" }
}'
For a shipment, you can create its boxes in the same call. shipment.packaging: itemized takes 1 to 20 shipment.packages, each with non-empty items naming only lines in the request's line_items. Their totals can cover less than, but not more than, each requested quantity. For one box holding every requested unit, send packaging: single_package and a shipment.package without items. This reships three units from another warehouse:
curl -X POST https://api.withflintpay.com/v1/fulfillments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-1042-reship" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ord_1kmn0aExample",
"type": "shipment",
"line_items": [
{ "order_line_item_id": "li_1kmn0aExampleA", "bundle_component_id": null, "quantity": 1 },
{ "order_line_item_id": "li_1kmn0aExampleB", "bundle_component_id": null, "quantity": 1 },
{ "order_line_item_id": "li_1kmn0aExampleC", "bundle_component_id": null, "quantity": 1 }
],
"external_reference_id": "wms-order-1042-reship",
"shipment": {
"packaging": "itemized",
"packages": [
{
"status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456786",
"items": [
{ "order_line_item_id": "li_1kmn0aExampleA", "quantity": 1 },
{ "order_line_item_id": "li_1kmn0aExampleB", "quantity": 1 }
]
},
{
"status": "shipped", "carrier": "ups", "tracking_number": "1Z999AA10123456787",
"items": [{ "order_line_item_id": "li_1kmn0aExampleC", "quantity": 1 }]
}
]
}
}'
The response is the new fulfillment, with the created shipment and packages in its shipments and packages fields. An item for a line outside line_items returns 400 INVALID_REQUEST with detail NOT_ALLOWED, and the item that pushes a line over its requested quantity returns detail INVALID_VALUE. Both name the item in param.
Each fulfillment line item includes bundle_component_id: send the component ID from the order line's bundle_components, or null when the line isn't a bundle component. For bundles, quantity counts component units. Responses, including buyer fulfillments and each line's fulfillment_quantities, use the same identity. A bundle line without its component ID returns 400 INVALID_REQUEST with detail REQUIRED; a component outside that line returns detail INVALID_VALUE. Both name line_items[i].bundle_component_id.
A fully assigned, fulfilled, canceled, or refunded line returns 409 ACTION_NOT_ALLOWED. A line whose fulfillment profile does not allow the requested type returns 400 INVALID_REQUEST with detail NOT_ALLOWED at line_items[i].order_line_item_id. These refusals happen before any fulfillment or inventory change.
- Quantities are capped. A line can be split across several fulfillments, but a request can't claim more than the
unassigned_quantityin the line'sfulfillment_quantities(see Read what is left to fulfill). Asking for more returns409 LIMIT_EXCEEDEDwith the quantity field inparamand the remaining amount indetails[0].available_quantity. - Tracked stock comes from one location. For inventory items, a fulfillment draws on stock committed at a single location, so stock committed at two locations needs two fulfillments.
- Backordered units can't be claimed. A line sold on backorder keeps those units in
unassigned_quantityuntil stock fills them, so the quantity you can fulfill now isunassigned_quantityminus the line'sbackordered_quantity. A request for more than that, but not more thanunassigned_quantity, returns409 INVENTORY_INSUFFICIENTwith the units that can be fulfilled indetails[0].available_quantity. Retry whenorder.updatedshows the line'sbackordered_quantityhas fallen. See Backordered and pre-ordered lines. - Release dates don't hold a fulfillment. A line's
release_dateandexpected_ship_datetell you and the buyer when to expect the goods. Flint doesn't block a fulfillment before either date. - The address comes from the order. Without
recipient, Flint copies the order's delivery destination and buyer email. - Supply an
Idempotency-Keyfor every fulfillment create. An inline shipped package can consume stock, so the key is required for every body. A missing key returns400 INVALID_REQUESTwith detailREQUIREDatIdempotency-Key. Store it before you send, so after a timeout you can replay the same key and body and get the original IDs.external_reference_idlets you find the fulfillment later withGET /v1/fulfillments?order_id=...&external_reference_id=....
Cancel, fail, and try again#
Canceling and failing both end a fulfillment, but they leave the order in different places:
| Action | Stock | Quantity | Use it when |
|---|---|---|---|
cancel | Released | Stays with the fulfillment and counts in the line's canceled_quantity | The goods won't be sent at all |
fail with release_quantity: true | Released, unless it already left on hand. A shipment fulfillment with a shipment that isn't voided returns 409 RESOURCE_IN_USE instead | Returns to the line's unassigned_quantity | You'll send it another way, such as from another warehouse |
fail with release_quantity: false | Stays committed or consumed | Stays with the fulfillment and counts in the line's failed_quantity | The goods are gone, such as a parcel lost after it shipped |
When every required unit is fulfilled, canceled, removed, or failed without release, the order leaves the unfulfilled work queue. Any failed quantity makes this terminal aggregate fulfillment_status: closed; the line still reports failed_quantity. A released failure leaves its units outstanding.
A no_show counts in canceled_quantity too. After a fail with release_quantity: true, read the line's unassigned_quantity and create the replacement:
curl -X POST https://api.withflintpay.com/v1/fulfillments/ful_1kmn0aExample/fail \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ful_1kmn0aExample-fail" \
-H "Content-Type: application/json" \
-d '{ "release_quantity": true, "reason_message": "Out of stock at the east warehouse" }'
While a fulfillment has a shipment that isn't voided, cancel drops out of supported_actions, and fail with release_quantity: true returns 409 RESOURCE_IN_USE with the shipment in details[0].blocking_resources. Before handoff, void the shipment first. Once a parcel has left, its shipment can't be voided, so fail with release_quantity: false is the way to end the fulfillment without completing it.
When a payment stops shipping#
A payment provider can ask Flint to stop shipping for a payment, for example while it reviews the payment. Every open fulfillment on the order then goes on hold with reason payment_review, and only cancel and hold remain in supported_actions. Any other action, including release_hold, returns 409 ACTION_NOT_ALLOWED with details[0].reason: on_hold. You receive payment_intent.fulfillment_hold_updated when the stop starts and again when it lifts.
Lifting the payment stop leaves the fulfillment on_hold. You can send release_hold or the next forward action. Later package progress can also advance a hold placed by Flint once the payment stop lifts; it never advances a merchant hold.
A Flint payment review also places a Flint-owned payment_review hold on open fulfillments and any created while the review is open or resolving. Dispatch is blocked as soon as the review opens. Approving releases this payment hold and restores only the fulfillments it held, provided no other payment hold covers the order. Merchant holds stay in place. Expiry and lifecycle closure, such as a refund, dispute, or payment cancellation, release the payment hold but leave fulfillment on_hold for you to reevaluate. Send release_hold explicitly before advancing this work; forward actions and package progress do not release an unapproved review hold. Declining keeps the payment hold active, including when a failed refund reopens the review.
Review holds and provider stops release independently. Payment review events describe the review; payment_intent.fulfillment_hold and payment_intent.fulfillment_hold_updated continue to describe provider stops only.
For a subscription renewal that cannot ship, an out_of_stock refund that returns the remaining payment cancels eligible unshipped shipment fulfillments and releases their stock. Other refunds leave fulfillment quantities unchanged. Returned goods come back through Returns.
Take items off a paid order#
To drop an item before it ships, such as a line that ran out of stock, edit the order. The edit refunds the removed units and releases their stock in one step, and the units count like canceled ones in the order's fulfillment_status. It removes only unassigned_quantity, so a unit a fulfillment already holds has to leave it first:
| The units are | What to do |
|---|---|
| Unassigned | Edit the order |
| In a fulfillment that hasn't been handed off | End the fulfillment with fail and release_quantity: true, then edit the order. The edit returns 409 LIMIT_EXCEEDED with details[0].available_quantity until the units are unassigned. |
| Dispatched or delivered | Create a Return. An edit can't remove them. |
cancel leaves the quantity with the fulfillment as canceled_quantity, so an edit can't remove it. A removed unit never returns to unassigned_quantity, so don't plan to fulfill it later.
What the buyer receives#
Flint sends the buyer one email per moment, from the call that reports it:
| Source | Emails on |
|---|---|
| Package actions | mark_shipped, mark_out_for_delivery, mark_delivery_attempted, mark_delivered, mark_exception, and mark_returned, once per package. A package created as shipped counts as mark_shipped |
| Fulfillment actions | mark_ready, complete, cancel, fail, mark_no_show, and dispatch for local delivery |
| A shipment without packages | dispatch sends the shipped email, and complete the delivered email |
Nothing else emails: not accept, mark_picked, mark_packed, mark_preparing, schedule, start, hold, release_hold, mark_in_transit, tracking corrections, or entries posted to the events endpoint. When packages move a fulfillment to dispatched or completed, the package email is the only one, and a dispatch or complete you send stays silent when a package already sent that moment. Flint also drops a repeat of a moment it already recorded, such as two integrations both reporting that the same package shipped.
- Recipient. Each email goes to the fulfillment's
recipient.email. Without one, Flint uses the order'sbuyer_contact.email, then the email of the order's customer. With no address at all, the email is skipped withsuppression_reason: recipient_missing. - Skipping one. Send
buyer_notification_behavior: suppresson the action. Failing a fulfillment withrelease_quantity: trueskips the failure email by default so you can reassign or edit the items. Sendbuyer_notification_behavior: sendwhen the buyer needs to know about a failure. - Shipping address changes. Changing a paid order's shipping address on its fulfillment emails the new address to the order buyer, even if the fulfillment has a different recipient. Changing the address in Flint leaves any carrier rerouting to you.
- Ship date changes. When you change a paid line's
expected_ship_date, Flint emails the buyer the new date. See Change an expected ship date. - Unsubscribes. Buyers can unsubscribe from shipping progress emails: shipped, out for delivery, delivered, a local delivery's dispatch, and ship date changes. Every other email always goes out.
- Sending your own. Set
customer_email_delivery.fulfillment_updatestomerchant_sendsand Flint sends none of these. See Customer email delivery.
A signed-in buyer can read their own fulfillments, shipments, and packages through GET /v1/me/fulfillments, /v1/me/shipments, and /v1/me/packages with a customer session.
GET /v1/me/packages and GET /v1/me/packages/{package_id} include an items list for each outbound package with allocated items. Match each order_line_item_id to a line on the buyer's order. Use the package's status to tell whether those items have shipped. When an item has a bundle_component_id, its quantity counts units of that component.
Read events and notifications#
Writes return the resource they changed, not the records they logged. Read those through their lists:
GET /v1/fulfillment-events?fulfillment_id=...returns the timeline: every status change, withprevious_statusandcurrent_status, plus tracking changes and carrier scans. Filter bypackage_id,shipment_id,order_id, orevent_type. Sort byreceived_at(the default) oroccurred_at, withsort_directiondesc(the default) orasc.GET /v1/fulfillment-notifications?fulfillment_id=...returns the email record. Each entry has astatusofpending,sent,failed, orsuppressed, and asuppression_reasonwhen it was skipped. Filter byfulfillment_event_idto find the email a step sent.
Staying in sync#
Each event carries its resource in data.object, as its GET returns it. A status change sends exactly one fulfillment event: fulfillment.completed, fulfillment.canceled, or fulfillment.failed for those statuses, with no fulfillment.updated, and fulfillment.updated for every other status. Changes to the order's embedded fulfillments or fulfillment_status send order.updated, and order.closed is sent only when the order moves from open to closed. Delivery details are in the event catalog.
- Calls you make send events too. Resources a call creates send their
.createdevents at their final revision, with no.updatedevents of their own. The call also sends its timeline entries and the fulfillment and order events for any progress it causes. Adding a package to an existing shipment sendspackage.createdand ashipment.updatedwith the finalpackage_count. - Tracking changes are timeline entries. A tracking change, through
PATCHormark_shipped, sendspackage.updatedand afulfillment_event.createdwithevent_type: tracking_updated. A correction alone sends no fulfillment or order event. - Contents aren't in the package snapshot. Creating, editing, or deleting a package item advances the package's
versionand sends onepackage.updated. When you receive a package with a higherversionthan your copy, listGET /v1/packages/{package_id}/items, paging to the end, to refresh its contents. - Deliveries can repeat or arrive out of order. Deduplicate by
webhook_event_id, and replace a stored fulfillment, shipment, or package only when the snapshot'sversionis higher. A retry resends the original snapshot, so fetch the resource when you need its current state. - Updates aren't moments. An update event says a resource changed. It isn't a timeline entry and doesn't mean the buyer got an email. To send your own mail, key it to the moments Flint emails for, which
fulfillment_event.createdrecords.
Common errors#
The full list is in the error reference.
Endpoints#
Units reserved by a pending order edit#
When pending_order_edit_id is set, the units that edit removes remain in unassigned_quantity, but cannot join a fulfillment until the edit ends. You can still assign the free units. A claim that needs reserved units returns 409 ACTION_NOT_ALLOWED, reason order_edit_pending, at the quantity field and names the edit. Cancel the edit or wait for its payment before trying again. Fulfill added items only after the edit completes.