FlxpointBeta
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

  1. Every few minutes, call GET /fulfillment-requests with filterStatus=Processing,Processed, filterIsAcknowledged=false and filterIsCanceled=false.
  2. Store each fulfillment request on your side, keyed by its id.
  3. Acknowledge it with PATCH /fulfillment-requests/{id}/acknowledge, optionally sending your own reference as confirmationNumber.
  4. Page with filterPageNumber and filterPageSize (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"
  • filterStatus takes 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=false returns only requests not yet acknowledged, which is what makes acknowledging your fence: once you acknowledge one, it stops coming back.
  • filterPageSize defaults to 20 and allows up to 100; filterPageNumber starts 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, filterCanceledAfter and filterVoidedAfter, plus sinceId (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}/processing moves Unprocessed to Processing, the API equivalent of the Process action in the Flxpoint app. Any other starting status is a 400, and repeating it on a request already in Processing returns 200. Requests whose supplier receives them through the Vendor Portal are rejected with 400, because those go straight to Processed.
  • PATCH /fulfillment-requests/{id}/processed moves Processing to Processed, and returns 200 if the request is already Processed.
Don't read through GET /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 recommends GET /fulfillment-requests to read and /acknowledge to 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 401 or 404 will 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

Was this page helpful?
Can't find what you need?