Skip to content

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.

A shipped order, end to endResponse
Your serverFlintBuyerfulfillment.created, shortly after paymentmark_picked or mark_packed (optional)POST /v1/shipments with shipped packagesshipped email for each package, with trackingfulfillment.updated, status dispatchedmark_delivered on each packagedelivered email for each packagefulfillment.completed
  1. Flint sends fulfillment.created, shortly after payment to Your server
  2. Your server sends mark_picked or mark_packed (optional) to Flint
  3. Your server sends POST /v1/shipments with shipped packages to Flint
  4. Flint sends shipped email for each package, with tracking to Buyer
  5. Flint sends fulfillment.updated, status dispatched to Your server
  6. Your server sends mark_delivered on each package to Flint
  7. Flint sends delivered email for each package to Buyer
  8. 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:

typeSteps you sendStock leaves on hand at
shipmentaccept, mark_picked, mark_packed, then package actionsdispatch, or complete if it skips dispatch
local_deliveryaccept, mark_preparing, dispatch, completedispatch, or complete if it skips dispatch
pickupaccept, mark_preparing, mark_ready, completecomplete
digitalaccept, completecomplete
serviceaccept, schedule, start, completecomplete

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
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
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
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
curl "https://api.withflintpay.com/v1/packages?carrier=ups&tracking_number=1Z999AA10123456784" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "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
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
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 }'
Response
{
  "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's version. A stale value returns 409 VERSION_CONFLICT and changes nothing.
  • Each route takes only its own fields, and no action. hold needs a reason, schedule needs scheduled_start_at and scheduled_end_at, fail needs release_quantity, and mark-no-show needs a reason. Every route accepts occurred_at for when it happened and reason_message, an internal note of up to 500 characters. Flint keeps this note out of buyer emails.
  • Retry with the same Idempotency-Key and body. A replay returns the original result without another email. See Idempotency.
  • supported_actions follows 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 fulfillment
Final values do not change again
  • pending
    Created, and nobody has started or accepted the work.
  • accepted
    Someone accepted the work, which hasn't started.
  • scheduled
    A service appointment window is booked.
  • in_progress
    Service work has started, or at least one outbound package has shipped and the fulfillment has yet to reach full dispatch.
  • preparing
    A pickup or local delivery is being prepared.
  • picked
    The shipment's items are picked.
  • packed
    The shipment's items are packed.
  • ready
    A pickup is waiting for the buyer.
  • dispatched
    The goods have left for delivery. dispatched_at records when.
  • on_hold
    Work is paused. active_hold gives the reason and the status it paused at.
  • completedFinal
    All the work is done. completed_at records the delivery or handover time when it is known.
  • canceledFinal
    The work was called off.
  • failedFinal
    The work couldn't be finished.
  • no_showFinal
    A service appointment was missed. outcome records the reason.

active_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
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_hold returns it to previous_status. It keeps the schedule and progress timestamps such as picked_at and packed_at, never emails the buyer, and rejects buyer_notification_behavior.
  • Any other action that previous_status allows, except hold, moves it on and clears the hold. A fulfillment held at packed accepts dispatch but not mark_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
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 }]
      }
    ]
  }'
Response
{
  "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: created or status: shipped. For a shipped package, send 1 to 100 entries in items, with each order line and bundle component at most once per box. To ship the entire fulfillment in one package, set pack_fulfillment_items: true on the package and omit items. Omitting both returns 400 INVALID_REQUEST with detail REQUIRED at the package's items field. Across all packages, quantities can't exceed what the fulfillment covers for that component.
  • Check the fulfillment version. Send expected_fulfillment_version on the shipment or standalone package request to use the version you last read. If the fulfillment changed, Flint refuses the request with 409 VERSION_CONFLICT before creating any shipping records.
  • Create labels before handoff. Send status: created, then mark_shipped on each package when the carrier takes it. To add a box later, use POST /v1/packages.
  • Choose when to email. Each shipped package sends one shipped email with its tracking link. Set buyer_notification_behavior: suppress on a package to skip its email. shipped_at defaults to the request time. Both fields are allowed only with shipped.
  • Retry with the same Idempotency-Key and body. A replay returns the original IDs and sends no second email. external_reference_id helps you find a shipment later but doesn't prevent duplicates.
  • The delivery address is on the fulfillment. recipient holds the address and buyer email copied from the order. If the buyer asks for a change, update it with PATCH /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
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:

Response
{
  "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
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.

RoutePackage statusBuyer email
/mark-packedpackedNone
/mark-shippedshippedShipped, with the tracking link
/mark-in-transitin_transitNone
/mark-out-for-deliveryout_for_deliveryOut for delivery
/mark-delivery-attempteddelivery_attemptedDelivery attempted
/mark-delivereddeliveredDelivered
/mark-exceptionexceptionDelivery issue
/mark-returnedreturnedReturned 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
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
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 (shipped or later). dispatched_at is the latest package's shipped_at, and stock leaves on hand.
  • Completed once, with every unit packed, every package is delivered. completed_at is the latest package's delivered_at, so a return window that starts at delivery counts from the carrier's delivery. The order's fulfillment_status updates and fulfillment.completed fires. A package in exception or returned prevents 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
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_ready emails the buyer that the order is waiting. complete records the collection and takes the stock off hand. For a buyer who never comes, send cancel or fail; mark_no_show is for services only. pickup_details names the store, and recipient.instructions holds any note the buyer left for it.
  • Local delivery. Works like a shipment without shipments or packages: dispatch when the courier leaves, which emails the buyer, then complete on delivery. Put the courier's link in local_delivery_details.tracking_url.
  • Digital. Only a line that requires a digital fulfillment gets one: a custom line with that requirement, or a catalog line whose variant has a manual profile with allowed_types ["digital"]. Create it yourself after the order is paid. Put the download link in digital_details.delivery_url and send complete once 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/me return delivery_url as null and 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 on order.refunded or order.partially_refunded. A catalog digital variant with no profile gets no fulfillment, so deliver it from your app after order.paid and a check of the order's dispute_status.
  • Service. Only a line that requires a service fulfillment gets one, from a custom line or a catalog variant with a manual profile with allowed_types ["service"]. A service is fulfilled as service, never as digital. schedule books the appointment window, start marks it underway, and mark_no_show records a missed appointment with a reason, such as customer_no_show.
  • Handover. For a counter sale where the buyer leaves with the goods, set the order's handover instead of a delivery choice. When the order is paid, Flint creates one handover fulfillment at the handover location and completes it in the same step, so it arrives already completed, with fulfillment.created and fulfillment.completed and no buyer email. You can't create or advance a handover fulfillment 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
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
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_quantity in the line's fulfillment_quantities (see Read what is left to fulfill). Asking for more returns 409 LIMIT_EXCEEDED with the quantity field in param and the remaining amount in details[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_quantity until stock fills them, so the quantity you can fulfill now is unassigned_quantity minus the line's backordered_quantity. A request for more than that, but not more than unassigned_quantity, returns 409 INVENTORY_INSUFFICIENT with the units that can be fulfilled in details[0].available_quantity. Retry when order.updated shows the line's backordered_quantity has fallen. See Backordered and pre-ordered lines.
  • Release dates don't hold a fulfillment. A line's release_date and expected_ship_date tell 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-Key for every fulfillment create. An inline shipped package can consume stock, so the key is required for every body. A missing key returns 400 INVALID_REQUEST with detail REQUIRED at Idempotency-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_id lets you find the fulfillment later with GET /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:

ActionStockQuantityUse it when
cancelReleasedStays with the fulfillment and counts in the line's canceled_quantityThe goods won't be sent at all
fail with release_quantity: trueReleased, unless it already left on hand. A shipment fulfillment with a shipment that isn't voided returns 409 RESOURCE_IN_USE insteadReturns to the line's unassigned_quantityYou'll send it another way, such as from another warehouse
fail with release_quantity: falseStays committed or consumedStays with the fulfillment and counts in the line's failed_quantityThe 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
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 areWhat to do
UnassignedEdit the order
In a fulfillment that hasn't been handed offEnd 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 deliveredCreate 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:

SourceEmails on
Package actionsmark_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 actionsmark_ready, complete, cancel, fail, mark_no_show, and dispatch for local delivery
A shipment without packagesdispatch 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's buyer_contact.email, then the email of the order's customer. With no address at all, the email is skipped with suppression_reason: recipient_missing.
  • Skipping one. Send buyer_notification_behavior: suppress on the action. Failing a fulfillment with release_quantity: true skips the failure email by default so you can reassign or edit the items. Send buyer_notification_behavior: send when 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_updates to merchant_sends and 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, with previous_status and current_status, plus tracking changes and carrier scans. Filter by package_id, shipment_id, order_id, or event_type. Sort by received_at (the default) or occurred_at, with sort_direction desc (the default) or asc.
  • GET /v1/fulfillment-notifications?fulfillment_id=... returns the email record. Each entry has a status of pending, sent, failed, or suppressed, and a suppression_reason when it was skipped. Filter by fulfillment_event_id to 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 .created events at their final revision, with no .updated events 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 sends package.created and a shipment.updated with the final package_count.
  • Tracking changes are timeline entries. A tracking change, through PATCH or mark_shipped, sends package.updated and a fulfillment_event.created with event_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 version and sends one package.updated. When you receive a package with a higher version than your copy, list GET /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's version is 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.created records.

Common errors#

  • HTTP 409
    The current state refuses the action. Branch on details[0].reason. unsupported_state: the action isn't in supported_actions, including fulfillment actions while the order is unpaid, or contents, new packages, or a void came after handoff; details[0] carries the current status, version, and supported_actions. status_not_reached: the order isn't paid when creating or editing fulfillment data, or the fulfillment needs accept first before its data can change. An action sent before accept or before payment is unsupported_state. on_hold: a payment is holding fulfillment, so only cancel and hold work. terminal_status: the fulfillment, shipment, or package has ended; package and shipment corrections still work until they are voided. field_locked: a completed fulfillment's details can't be replaced, and param names the field. derived_from_packages: packages set this fulfillment's completed_at.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The expected_version you sent is stale (param names it), or another change landed while your request ran (no param). details[0].current_resource is the current fulfillment, shipment, or package. Read it again, decide again, and send the new request with a new Idempotency-Key.
  • HTTP 409
    A quantity is more than what is left. When creating a fulfillment, read the line's unassigned_quantity; details[0].available_quantity has the remaining amount. For package items, reduce the quantity or move it to another package.
  • HTTP 409
    The fulfillment claims units that are still on backorder. details[0].available_quantity is the quantity that can be fulfilled now. Create the fulfillment for that quantity, and the rest when stock fills the backorder.
  • HTTP 409
    OPERATION_IN_PROGRESSRetry the same request
    With delivery_selection_materializing, Flint is still creating the fulfillments for the buyer's delivery choice. Wait for fulfillment.created and use those fulfillments.
  • HTTP 409
    A shipment that isn't voided still holds the quantity. Void the shipment in details[0].blocking_resources, then cancel or fail.
  • HTTP 409
    An external_event_id was reused with different details. Send a new ID for a new event.
  • HTTP 400
    A field is missing, unknown for this action, or invalid; param names it. Common causes are a field another action owns, null tracking on mark_shipped, and a status sent as an event_type.

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.

Was this helpful?