Browse the docs
Polling Fulfillment Requests
GET /fulfillment-requests is how a Source finds the work Flxpoint has sent it. With a Source token it returns only that source's fulfillment requests; with an Account token, the account's. This guide covers the poll that returns only what is new, how to page through it, and how acknowledging closes the loop.
The short version
- Every few minutes, call
GET /fulfillment-requestswithfilterStatus=Processing,Processed,filterIsAcknowledged=falseandfilterIsCanceled=false. - Store each fulfillment request on your side, keyed by its
id. - Acknowledge it with
PATCH /fulfillment-requests/{id}/acknowledge, optionally sending your own reference asconfirmationNumber. - Page with
filterPageNumberandfilterPageSize(up to 100) until a page comes back short.
The poll
curl -G "https://api.flxpoint.com/fulfillment-requests" \
-H "X-API-TOKEN: YOUR_SOURCE_TOKEN" \
--data-urlencode "filterStatus=Processing,Processed" \
--data-urlencode "filterIsAcknowledged=false" \
--data-urlencode "filterIsCanceled=false" \
--data-urlencode "filterPageSize=100" \
--data-urlencode "filterPageNumber=1"filterStatustakes a comma-separated list. Processing and Processed are the statuses of a fulfillment request that has been sent on for fulfillment; the full list is on the endpoint reference.filterIsAcknowledged=falsereturns only requests not yet acknowledged, which is what makes acknowledging your fence: once you acknowledge one, it stops coming back.filterPageSizedefaults to 20 and allows up to 100;filterPageNumberstarts at 1. The response is a JSON array of fulfillment requests, so a page shorter than your page size is the last one.- There is no general "updated after" filter on this endpoint. There are event filters instead:
filterGeneratedAfter,filterSentAfter,filterAcknowledgedAfter,filterCanceledAfterandfilterVoidedAfter, plussinceId(only IDs greater than the one you pass). Use them when you need a time window rather than a status.
Acknowledge what you have stored
curl -X PATCH "https://api.flxpoint.com/fulfillment-requests/12345/acknowledge" \
-H "X-API-TOKEN: YOUR_SOURCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "confirmationNumber": "YOUR-ORDER-REF-881" }'Acknowledging marks every line item quantity on the request that is not already acknowledged or canceled as acknowledged. The body is optional: confirmationNumber is your own reference for the request. A 200 means it worked; 401 is a token problem and 404 an unknown ID.
Store first, then acknowledge. If your handler crashes in between, the request is still unacknowledged and comes back on the next poll, which is what you want. Acknowledging first and crashing before you store it would lose the request on your side.
Putting it together
// Pseudo-code. Adapt to your stack.
async function pullNewFulfillmentRequests() {
for (let page = 1; ; page++) {
const res = await flx.get("/fulfillment-requests", {
filterStatus: "Processing,Processed",
filterIsAcknowledged: false,
filterIsCanceled: false,
filterPageSize: 100,
filterPageNumber: page,
});
const frs = await res.json(); // a JSON array of fulfillment requests
for (const fr of frs) {
// Idempotent on fr.id: a crash between "stored" and "acknowledged"
// brings the same FR back on the next poll.
await db.saveFulfillmentRequestOnce(fr); // INSERT ... ON CONFLICT DO NOTHING
await flx.patch(`/fulfillment-requests/${fr.id}/acknowledge`, {
confirmationNumber: await db.yourReferenceFor(fr.id),
});
}
if (frs.length < 100) return; // last page
}
}
// Run it every few minutes from one scheduler or worker per token.Idempotency: handle replays safely
Because a request reappears until it is acknowledged, every handler must be safe to run twice for the same id. Two ways that work:
- A unique constraint on your side.
INSERT ... ON CONFLICT (flxpoint_fr_id) DO NOTHING. The second insert is a no-op. - Check, then act, in one transaction. Look up the ID, skip it if found, otherwise insert it and run your side effects in the same transaction.
Moving a request through processing
Two endpoints move a fulfillment request between processing states without touching anything else:
PATCH /fulfillment-requests/{id}/processingmoves Unprocessed to Processing, the API equivalent of the Process action in the Flxpoint app. Any other starting status is a400, and repeating it on a request already in Processing returns200. Requests whose supplier receives them through the Vendor Portal are rejected with400, because those go straight to Processed.PATCH /fulfillment-requests/{id}/processedmoves Processing to Processed, and returns200if the request is already Processed.
Don't read throughGET /fulfillment-requests/processing. It returns the requests in Processing and moves all of them to Processed as a side effect, so a request is marked processed even if the response never reaches you. The reference itself recommendsGET /fulfillment-requeststo read and/acknowledgeto respond.
Can a webhook replace the poll?
FulfillmentRequestProcessingEvent can tell you sooner that a request moved into Processing, but it should not be your only trigger. It is never sent for requests whose supplier receives them through the Vendor Portal, since those skip Processing, and an event that cannot be built at the moment it is generated is dropped without an error. Use it to poll sooner, and keep the poll as the source of truth. The Webhooks guide covers setting it up and reading its delivery log.
Polling cadence
Every 1 to 5 minutes suits most sources; poll faster only if your volume needs it. Every call counts against the 2 requests per second per token limit, so page one request at a time and run a single poller per token rather than several in parallel.
Tracking orders instead? Poll GET /orders
If you are not the one fulfilling requests and you want to know when anything on an order changed, GET /orders with orderModifiedAfter covers it in one call: it returns orders where the order or any of its parts changed after that time, including line items, addresses, fulfillment requests, shipments, source invoices and returns. updatedAfter is narrower and only sees changes to the order itself.
# One poll for everything that changed on your orders since the last run.
curl -G "https://api.flxpoint.com/orders" \
-H "X-API-TOKEN: YOUR_TOKEN" \
--data-urlencode "orderModifiedAfter=${LAST_RUN}" \
--data-urlencode "includeShipments=true" \
--data-urlencode "pageSize=100" \
--data-urlencode "page=1"
# Store the time you started this run as the next LAST_RUN.Syncing data incrementally has the same pattern for every resource.
Anti-patterns to avoid
- Full mirror syncs. Pulling every fulfillment request on every cycle to diff against a local snapshot wastes your rate limit and builds a second source of truth. Filter by status and acknowledgement instead.
- Polling without filters. With no filters the endpoint returns everything visible to the token.
- Parallel pollers on the same token. Two processes share one 2 requests per second budget and slow each other down. Run one poller per token.
- Retrying a 4xx in a loop. A
401or404will not succeed on retry. Log it and move on; retry only timeouts and 5xx responses. - Acknowledging before your side has committed. If you pass the request to another system (an ERP, a warehouse), acknowledge Flxpoint only after that step has committed.
Related
- Fulfillment Request: every endpoint and filter
- Integrating as a Source: the full Source-side flow
- Webhooks: events, delivery log and retries
- Authentication & Rate Limits