Filld Developer Documentation

API Reference

Complete endpoint reference for SCN Portal Integration for Evergreen (the Partner Slots API). All requests go to https://api.filld.dev/api/v1 with your x-api-key header. For concepts, lifecycle, and integration recipes, read the Documentation. A full sandbox is available: test keys (evg_test_) run every endpoint identically with zero real-world impact — see Sandbox & Testing.

Delivery Availability

Check which delivery windows serve an address.

2 endpoints

Reservations

Book delivery slots — one call — and release them if plans change.

5 endpoints

Orders

Drop-in replacement for the POS create-order API.

6 endpoints

Delivery Availability

Check which delivery windows serve an address.

Check Availability

Auth: x-api-key

POSThttps://api.filld.dev/api/v1/delivery/availability

Check whether an address is inside the delivery area and list the delivery windows currently open for it.

Parameter	In	Type	Required	Description
address	body	object	Required	Delivery address to check. The same fields are also accepted flat at the top level of the body.
address.street	body	string	Recommended	Street address, including the house number.
address.city	body	string	Recommended	City name.
address.state	body	string	Recommended	Two-letter state code.
address.zip	body	string	Required	5-digit ZIP code. Send the full address as well — ZIP-only checks fall back to coarser ZIP-level coverage.

addressbodyobjectRequired: Delivery address to check. The same fields are also accepted flat at the top level of the body.
address.streetbodystringRecommended: Street address, including the house number.
address.citybodystringRecommended: City name.
address.statebodystringRecommended: Two-letter state code.
address.zipbodystringRequired: 5-digit ZIP code. Send the full address as well — ZIP-only checks fall back to coarser ZIP-level coverage.

Request

curl -X POST "https://api.filld.dev/api/v1/delivery/availability" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "12 Main St",
      "city": "Monsey",
      "state": "NY",
      "zip": "10952"
    }
  }'

Response — 200 OK

{
  "covered": true,
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "slots": [
    {
      "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
      "date": "2026-07-07",
      "dayOfWeek": 2,
      "window": { "start": "09:00", "end": "12:00" },
      "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM",
      "orderBy": "2026-07-06T19:00:00.000Z",
      "availability": "available"
    }
  ]
}

slotId is an opaque token — pass it back verbatim to reserve; do not parse it or construct your own.
availability is "available" or "limited" (only a few spots left).
orderBy is the instant after which the slot can no longer be reserved.
Optional if you reserve by time (see Reserve a Slot) — recommended for showing customers accurate windows and order-by deadlines.

Status	Error code	When
200	—	Availability returned. covered: false with zone: null and empty slots when the address is outside the delivery area.
400	invalid_request	The address is missing or malformed.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

Check Availability (GET)

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/delivery/availability

Query-string variant of the availability check, intended for quick testing. Use the POST form in production.

Parameter	In	Type	Required	Description
street	query	string	Recommended	Street address, including the house number.
city	query	string	Recommended	City name.
state	query	string	Recommended	Two-letter state code.
zip	query	string	Required	5-digit ZIP code. ZIP-only checks fall back to coarser ZIP-level coverage.

streetquerystringRecommended: Street address, including the house number.
cityquerystringRecommended: City name.
statequerystringRecommended: Two-letter state code.
zipquerystringRequired: 5-digit ZIP code. ZIP-only checks fall back to coarser ZIP-level coverage.

Request

curl "https://api.filld.dev/api/v1/delivery/availability?street=12%20Main%20St&city=Monsey&state=NY&zip=10952" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "covered": true,
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "slots": [
    {
      "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
      "date": "2026-07-07",
      "dayOfWeek": 2,
      "window": { "start": "09:00", "end": "12:00" },
      "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM",
      "orderBy": "2026-07-06T19:00:00.000Z",
      "availability": "available"
    }
  ]
}

Status	Error code	When
200	—	Availability returned. covered: false with zone: null and empty slots when the address is outside the delivery area.
400	invalid_request	The address is missing or malformed.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

Reservations

Book delivery slots — one call — and release them if plans change.

Reserve a Slot

Auth: x-api-key

POSThttps://api.filld.dev/api/v1/delivery/reservations

Books a delivery slot. Provide slotId (from /availability) or the customer's requested time — by default the reservation is confirmed immediately and nothing else is required. Pass ttlMinutes for an opt-in checkout-start hold instead.

Parameter	In	Type	Required	Description
slotId	body	string	Conditional	The slot token returned by /availability, passed back verbatim. Provide slotId or time.
time	body	string	Conditional	ISO 8601 date-time, Eastern (offset-less = Eastern wall time) — the customer's requested delivery time. The reservation is booked into whichever offered window covers it; no prior /availability call required. Provide slotId or time.
address	body	object	Required	The delivery address for the order.
posOrderRef	body	string	Optional	Your POS order number, attached at creation — no confirm call needed.
customerRef	body	string	Optional	Your identifier for the customer. Opaque to Evergreen; echoed back on the reservation.
partnerOrderRef	body	string	Optional	Your order or cart identifier.
ttlMinutes	body	number	Optional	Opt-in hold mode: creates the reservation as "held" with an expiry, from 5 to 120 minutes; confirm it before it lapses. Omit for the default — an immediately confirmed booking.

slotIdbodystringConditional: The slot token returned by /availability, passed back verbatim. Provide slotId or time.
timebodystringConditional: ISO 8601 date-time, Eastern (offset-less = Eastern wall time) — the customer's requested delivery time. The reservation is booked into whichever offered window covers it; no prior /availability call required. Provide slotId or time.
addressbodyobjectRequired: The delivery address for the order.
posOrderRefbodystringOptional: Your POS order number, attached at creation — no confirm call needed.
customerRefbodystringOptional: Your identifier for the customer. Opaque to Evergreen; echoed back on the reservation.
partnerOrderRefbodystringOptional: Your order or cart identifier.
ttlMinutesbodynumberOptional: Opt-in hold mode: creates the reservation as "held" with an expiry, from 5 to 120 minutes; confirm it before it lapses. Omit for the default — an immediately confirmed booking.

Request

curl -X POST "https://api.filld.dev/api/v1/delivery/reservations" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
    "address": {
      "street": "12 Main St",
      "city": "Monsey",
      "state": "NY",
      "zip": "10952"
    },
    "customerRef": "cust_123"
  }'

Response — 201 Created

{
  "reservationId": "res_9f2c7a1e4b8d",
  "status": "confirmed",
  "slot": {
    "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
    "date": "2026-07-07",
    "window": { "start": "09:00", "end": "12:00" },
    "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM"
  },
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "expiresAt": null,
  "customerRef": "cust_123",
  "partnerOrderRef": null,
  "posOrderRef": null,
  "createdAt": "2026-07-03T14:15:00.000Z",
  "confirmedAt": "2026-07-03T14:15:00.000Z",
  "cancelledAt": null
}

This reservation object is the shape returned by every reservation endpoint. expiresAt is null for the default confirmed booking; in opt-in hold mode it is the instant the hold lapses if it is not confirmed.
One-call flow: pass time instead of slotId and the reservation is booked into whichever offered window covers the requested time (Eastern; offset-less = wall time) — no prior /availability call required. The response's slot tells you the window the time landed in; display that window to the customer.
Lifecycle values: confirmed (booked — the default), held (opt-in hold mode via ttlMinutes; must be confirmed before expiresAt), cancelled (released via DELETE), expired (an opt-in hold that lapsed; reserve again).
Reserve when the order is placed, not when the slots are displayed — a reservation consumes real capacity immediately.

Status	Error code	When
201	—	Slot booked (or hold created, when ttlMinutes is passed).
400	invalid_slot_id	The slot token is malformed.
400	invalid_request	The body is malformed, or neither slotId nor a parseable time was provided.
409	slot_unavailable	The window is full or no longer offered, or no delivery window covers the requested time — re-fetch availability.
409	order_by_passed	The slot's orderBy deadline has passed.
422	address_not_covered	The address is outside the delivery area.
422	zone_mismatch	The slot does not serve that address.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

List Reservations

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/delivery/reservations

List your organization's reservations, most recent first. Returns up to 100 reservations.

Parameter	In	Type	Required	Description
status	query	string	Optional	Filter by status: one of held, confirmed, cancelled, expired.
date	query	string	Optional	Filter by delivery date, YYYY-MM-DD (store-local).

statusquerystringOptional: Filter by status: one of held, confirmed, cancelled, expired.
datequerystringOptional: Filter by delivery date, YYYY-MM-DD (store-local).

Request

curl "https://api.filld.dev/api/v1/delivery/reservations?status=confirmed&date=2026-07-07" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "reservations": [
    {
      "reservationId": "res_9f2c7a1e4b8d",
      "status": "confirmed",
      "slot": {
        "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
        "date": "2026-07-07",
        "window": { "start": "09:00", "end": "12:00" },
        "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM"
      },
      "zone": { "id": "zone_mnsy01", "name": "Monsey" },
      "expiresAt": "2026-07-03T14:45:00.000Z",
      "customerRef": "cust_123",
      "partnerOrderRef": "cart_88213",
      "posOrderRef": "SO-448291",
      "createdAt": "2026-07-03T14:15:00.000Z",
      "confirmedAt": "2026-07-03T14:22:31.000Z",
      "cancelledAt": null
    }
  ]
}

Status	Error code	When
200	—	Reservations returned.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

Get a Reservation

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/delivery/reservations/{id}

Fetch a single reservation by its reservationId. A reservation belonging to another organization returns 404, the same as one that does not exist.

Parameter	In	Type	Required	Description
id	path	string	Required	The reservationId returned when the reservation was created.

idpathstringRequired: The reservationId returned when the reservation was created.

Request

curl "https://api.filld.dev/api/v1/delivery/reservations/res_9f2c7a1e4b8d" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "reservationId": "res_9f2c7a1e4b8d",
  "status": "confirmed",
  "slot": {
    "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
    "date": "2026-07-07",
    "window": { "start": "09:00", "end": "12:00" },
    "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM"
  },
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "expiresAt": null,
  "customerRef": "cust_123",
  "partnerOrderRef": null,
  "posOrderRef": null,
  "createdAt": "2026-07-03T14:15:00.000Z",
  "confirmedAt": "2026-07-03T14:15:00.000Z",
  "cancelledAt": null
}

Status	Error code	When
200	—	Reservation returned.
404	not_found	No such reservation in your organization.
401	unauthorized	Missing or invalid API key.

Confirm a Reservation

Auth: x-api-key

POSThttps://api.filld.dev/api/v1/delivery/reservations/{id}/confirm

Attach your POS order number to a reservation (optional). Required only to keep an opt-in hold alive — confirming a held reservation before expiresAt turns it into a booking.

Parameter	In	Type	Required	Description
id	path	string	Required	The reservationId to confirm.
posOrderRef	body	string	Optional	Your order number for the placed order. Strongly recommended.
partnerOrderRef	body	string	Optional	Your order or cart identifier.
customerRef	body	string	Optional	Your identifier for the customer.

idpathstringRequired: The reservationId to confirm.
posOrderRefbodystringOptional: Your order number for the placed order. Strongly recommended.
partnerOrderRefbodystringOptional: Your order or cart identifier.
customerRefbodystringOptional: Your identifier for the customer.

Request

curl -X POST "https://api.filld.dev/api/v1/delivery/reservations/res_9f2c7a1e4b8d/confirm" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "posOrderRef": "SO-448291",
    "partnerOrderRef": "cart_88213"
  }'

Response — 200 OK

{
  "reservationId": "res_9f2c7a1e4b8d",
  "status": "confirmed",
  "slot": {
    "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
    "date": "2026-07-07",
    "window": { "start": "09:00", "end": "12:00" },
    "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM"
  },
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "expiresAt": "2026-07-03T14:45:00.000Z",
  "customerRef": "cust_123",
  "partnerOrderRef": "cart_88213",
  "posOrderRef": "SO-448291",
  "createdAt": "2026-07-03T14:15:00.000Z",
  "confirmedAt": "2026-07-03T14:22:31.000Z",
  "cancelledAt": null
}

In the default flow this call is bookkeeping: it attaches posOrderRef so the store can reconcile the reservation against your order.
Idempotent: confirming an already-confirmed reservation updates the references and returns 200.

Status	Error code	When
200	—	References updated (and, in hold mode, the hold becomes a booking).
409	reservation_expired	(Hold mode) The hold lapsed before confirmation — reserve a new slot.
409	reservation_cancelled	The reservation was cancelled and cannot be confirmed.
404	not_found	No such reservation in your organization.
401	unauthorized	Missing or invalid API key.

Cancel a Reservation

Auth: x-api-key

DELETEhttps://api.filld.dev/api/v1/delivery/reservations/{id}

Cancel a hold or a confirmed reservation and release its capacity — for example, when the customer cancels the order or switches windows.

Parameter	In	Type	Required	Description
id	path	string	Required	The reservationId to cancel.

idpathstringRequired: The reservationId to cancel.

Request

curl -X DELETE "https://api.filld.dev/api/v1/delivery/reservations/res_9f2c7a1e4b8d" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "reservationId": "res_9f2c7a1e4b8d",
  "status": "cancelled",
  "slot": {
    "slotId": "slot_UGsxNDQzfDIwMjYtMDctMDc",
    "date": "2026-07-07",
    "window": { "start": "09:00", "end": "12:00" },
    "label": "Tue, Jul 7 · 9:00 AM – 12:00 PM"
  },
  "zone": { "id": "zone_mnsy01", "name": "Monsey" },
  "expiresAt": "2026-07-03T14:45:00.000Z",
  "customerRef": "cust_123",
  "partnerOrderRef": "cart_88213",
  "posOrderRef": null,
  "createdAt": "2026-07-03T14:15:00.000Z",
  "confirmedAt": null,
  "cancelledAt": "2026-07-03T14:31:02.000Z"
}

Cancelling an already-cancelled or expired reservation is a no-op that returns the current state.

Status	Error code	When
200	—	Reservation cancelled and capacity released (or already inactive).
404	not_found	No such reservation in your organization.
401	unauthorized	Missing or invalid API key.

Orders

Drop-in replacement for the POS create-order API.

Send an Order

Auth: x-api-key

POSThttps://api.filld.dev/api/v1/orders

Create an order. Returns 201 Created with an empty body and a Location header carrying the order number; the delivery window is validated and booked in the same call.

Header	Required	Description
x-api-key	Required	Your API key.
X-Customer-Pin	Conditional	Required when payment.method is "OnAccount" or when paying with a stored card.
Content-Type	Required	application/json.

Parameter	In	Type	Required	Description
customerId	body	string (≤8 chars)	Conditional	An existing customer account id. Provide customerId or customer.
customer	body	object	Conditional	Used when no customerId is provided. All fields within it are optional.
customer.firstName	body	string	Optional	Customer first name.
customer.lastName	body	string	Optional	Customer last name.
customer.phone	body	string	Optional	Customer phone number.
customer.email	body	string	Optional	Customer email address.
customer.address	body	object	Optional	addressLine1 (≤30 chars), addressLine2, city, state, zipCode.
externalOrderId	body	string (≤20 chars)	Optional	Your own order reference; must be unique per order. Used by GET /orders/external/{externalOrderId} and returned in webhook calls.
status	body	string	Optional	Initial order status: "OrderEntered" or "Unpicked".
items	body	array	Required	Order lines. Must be non-empty.
items[].productCode	body	string (≤12 chars)	Required	The item barcode.
items[].quantity	body	number	Required	Units; for by-weight lines ("Lbs"), the weight in pounds.
items[].description	body	string (≤30 chars)	Optional	Line description.
items[].priceQty	body	number	Optional	A divisor that determines the actual unit price (unitPrice ÷ priceQty).
items[].unitOfMeasure	body	string	Optional	"Unit", "Case", or "Lbs".
items[].unitPrice	body	number	Optional	Price per unit, in dollars.
items[].totalPrice	body	number	Optional	Line total, in dollars.
items[].note	body	string	Optional	Line note, visible to pickers and kitchen staff.
deliveryAddress	body	object	Delivery	The recipient of the order.
deliveryAddress.name	body	string	Optional	Recipient name.
deliveryAddress.phoneNumber	body	string	Optional	Recipient phone number.
deliveryAddress.address	body	object	Delivery	addressLine1 (≤30 chars), addressLine2, city (required for delivery), state, zipCode.
orderMethod	body	string	Optional	"Pickup" or "Delivery". Defaults to Delivery when deliveryAddress is present.
pickupDeliveryTime	body	string	Conditional	ISO 8601 date-time, Eastern time — the customer's requested time, booked into the delivery window that covers it, or the NEXT available window later that same day when the time falls before or between windows. A time past the day's last window is accepted and flagged unscheduled; a covering window that is FULL rejects with 409 slot_full (unless you hold a capacity boost). Required for Delivery orders without a reservationId.
note	body	string	Optional	Order-level note.
paymentEndpoint	body	object	Optional	url (string), headers (object of string→string) — your payment webhook, called at invoicing. Respond within 30 seconds or the invoice remains unpaid and requires manual processing.
payment	body	object	Optional	method: "OnAccount" \| "CreditCard"; cardId (string, optional — a stored card id).
priority	body	integer	Optional	Evergreen extension: 1 \| 2 \| 3 (1 = highest; omitted = normal). The store can use it to sequence work. Other values return 400 invalid_request.
reservationId	body	string	Optional	Evergreen extension: attach a previously reserved slot (res_…) to this order — it's confirmed automatically when the order is created.
store	body	string	Optional	Evergreen extension, pickup orders only: the fulfilling store, e.g. "uptown".

customerIdbodystring (≤8 chars)Conditional: An existing customer account id. Provide customerId or customer.
customerbodyobjectConditional: Used when no customerId is provided. All fields within it are optional.
customer.firstNamebodystringOptional: Customer first name.
customer.lastNamebodystringOptional: Customer last name.
customer.phonebodystringOptional: Customer phone number.
customer.emailbodystringOptional: Customer email address.
customer.addressbodyobjectOptional: addressLine1 (≤30 chars), addressLine2, city, state, zipCode.
externalOrderIdbodystring (≤20 chars)Optional: Your own order reference; must be unique per order. Used by GET /orders/external/{externalOrderId} and returned in webhook calls.
statusbodystringOptional: Initial order status: "OrderEntered" or "Unpicked".
itemsbodyarrayRequired: Order lines. Must be non-empty.
items[].productCodebodystring (≤12 chars)Required: The item barcode.
items[].quantitybodynumberRequired: Units; for by-weight lines ("Lbs"), the weight in pounds.
items[].descriptionbodystring (≤30 chars)Optional: Line description.
items[].priceQtybodynumberOptional: A divisor that determines the actual unit price (unitPrice ÷ priceQty).
items[].unitOfMeasurebodystringOptional: "Unit", "Case", or "Lbs".
items[].unitPricebodynumberOptional: Price per unit, in dollars.
items[].totalPricebodynumberOptional: Line total, in dollars.
items[].notebodystringOptional: Line note, visible to pickers and kitchen staff.
deliveryAddressbodyobjectDelivery: The recipient of the order.
deliveryAddress.namebodystringOptional: Recipient name.
deliveryAddress.phoneNumberbodystringOptional: Recipient phone number.
deliveryAddress.addressbodyobjectDelivery: addressLine1 (≤30 chars), addressLine2, city (required for delivery), state, zipCode.
orderMethodbodystringOptional: "Pickup" or "Delivery". Defaults to Delivery when deliveryAddress is present.
pickupDeliveryTimebodystringConditional: ISO 8601 date-time, Eastern time — the customer's requested time, booked into the delivery window that covers it, or the NEXT available window later that same day when the time falls before or between windows. A time past the day's last window is accepted and flagged unscheduled; a covering window that is FULL rejects with 409 slot_full (unless you hold a capacity boost). Required for Delivery orders without a reservationId.
notebodystringOptional: Order-level note.
paymentEndpointbodyobjectOptional: url (string), headers (object of string→string) — your payment webhook, called at invoicing. Respond within 30 seconds or the invoice remains unpaid and requires manual processing.
paymentbodyobjectOptional: method: "OnAccount" | "CreditCard"; cardId (string, optional — a stored card id).
prioritybodyintegerOptional: Evergreen extension: 1 | 2 | 3 (1 = highest; omitted = normal). The store can use it to sequence work. Other values return 400 invalid_request.
reservationIdbodystringOptional: Evergreen extension: attach a previously reserved slot (res_…) to this order — it's confirmed automatically when the order is created.
storebodystringOptional: Evergreen extension, pickup orders only: the fulfilling store, e.g. "uptown".

Request

curl -X POST "https://api.filld.dev/api/v1/orders" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "18452",
    "externalOrderId": "cart_88213",
    "orderMethod": "Delivery",
    "pickupDeliveryTime": "2026-07-07T10:00:00",
    "items": [
      {
        "productCode": "412009",
        "description": "Golden Flow OJ 64oz",
        "quantity": 2,
        "unitOfMeasure": "Unit",
        "unitPrice": 4.99,
        "totalPrice": 9.98
      },
      {
        "productCode": "286748",
        "description": "Chicken Cutlets",
        "quantity": 3.5,
        "unitOfMeasure": "Lbs",
        "unitPrice": 8.99,
        "note": "Sliced thin, please"
      }
    ],
    "deliveryAddress": {
      "name": "Chaim Brachfeld",
      "phoneNumber": "8455550142",
      "address": {
        "addressLine1": "12 Main St",
        "city": "Monsey",
        "state": "NY",
        "zipCode": "10952"
      }
    },
    "payment": { "method": "OnAccount" },
    "paymentEndpoint": {
      "url": "https://partner.example.com/webhooks/payment",
      "headers": { "x-webhook-secret": "whsec_XXXXXXXX" }
    },
    "note": "Leave by the side door"
  }'

Response — 201 Created (empty body)

HTTP/1.1 201 Created
Location: /orders/id/448291
x-evergreen-reservation-id: res_9f2c7a1e4b8d
x-evergreen-delivery-time: 2026-07-07T12:00:00-04:00
x-evergreen-store: uptown
x-evergreen-window: 2026-07-07 09:00-12:00

Contract-compatible with the POSwithLogic API: set your integration's base URL to https://api.filld.dev/api/v1 (instead of https://api.poswithlogic.dev) and use your Evergreen x-api-key — your existing /orders calls work unchanged. Same request body, same responses, same error format (RFC 7807 problem+json).
A successful create returns 201 Created; the Location header carries the order number (relative to the base URL). For accepted orders this is your Evergreen order reference (e.g. SCN1254) — the same number the store uses; orders forwarded straight to the fulfillment system return its id. Additional x-evergreen-* response headers carry scheduling and reservation info (reservation-id, delivery-time, store, window, sandbox).
Optional Evergreen extensions: reservationId — attach a previously reserved slot to the order (confirmed automatically when the order is created); store — pickup orders only, e.g. "uptown"; priority — integer 1 | 2 | 3 (1 = highest, omitted = normal), the store can use it to sequence work; other values return 400 invalid_request ("priority must be 1, 2 or 3 (1 = highest)"). A standard payload works as-is.
pickupDeliveryTime is the customer's requested time, booked into the delivery window that covers it (see Check Availability); the scheduled time stamped on the created order may be adjusted within that window as the store paces its day. Always show the customer the window, never the scheduled time.
A requested time before or between windows books the next available window later that same day. A time past the day's last window (or on a closed day) is still accepted (201) — flagged as slotOverride "unscheduled"; a past-deadline window flags "deadline". A FULL window rejects with 409 slot_full — check availability and pick another time (a capacity boost granted to your organization bypasses this). An address outside the delivery area is accepted for review: 201 with an x-evergreen-warning header and a JSON body (warning "outside_delivery_area") — the order is parked with the store; contact support to arrange fulfillment.
If the order cannot be created, any window capacity taken by the call is released; a reservation you referenced stays intact so you can retry.
Sandbox: orders created with a test key are not actually placed or fulfilled — you receive a TEST-prefixed order number (Location: /orders/id/TEST-48210937, plus x-evergreen-sandbox: true) and can exercise the full flow.
Sandbox failure simulation: include the string simulate=pos_error anywhere in note to receive a 400 in the standard problem+json format; any capacity taken by the call is released, as with a real failure.

Status	Error code	When
201	—	Order created — empty body; the Location header carries the order number.
400	invalid_request	The body is malformed, or a delivery order without reservationId has a missing or unparseable pickupDeliveryTime.
409	slot_full	The delivery window covering the requested time is full (no capacity boost). Pick another time.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.
Other	—	Any other error uses the same problem+json format ({ type, title, status, detail, code }).

Edit an Order

Auth: x-api-key

PATCHhttps://api.filld.dev/api/v1/orders/id/{orderNumber}

Edit an order while its tracking status is still accepted (not yet released to fulfillment). All body fields are optional; send at least one. Returns the updated order.

Parameter	In	Type	Required	Description
orderNumber	path	string	Required	The order number to edit.
items	body	array	Optional	Full replacement for the order's lines — same line shape as create. Must be non-empty when present.
pickupDeliveryTime	body	string	Optional	ISO 8601 date-time, Eastern — moves the order's slot booking. Same acceptance policy as create, including the closed-window override.
note	body	string	Optional	Replaces the order-level note.
priority	body	integer	Optional	1 \| 2 \| 3 (1 = highest, omitted = normal). Evergreen extension — the store can use it to sequence work. Other values return 400 invalid_request.

orderNumberpathstringRequired: The order number to edit.
itemsbodyarrayOptional: Full replacement for the order's lines — same line shape as create. Must be non-empty when present.
pickupDeliveryTimebodystringOptional: ISO 8601 date-time, Eastern — moves the order's slot booking. Same acceptance policy as create, including the closed-window override.
notebodystringOptional: Replaces the order-level note.
prioritybodyintegerOptional: 1 | 2 | 3 (1 = highest, omitted = normal). Evergreen extension — the store can use it to sequence work. Other values return 400 invalid_request.

Request

curl -X PATCH "https://api.filld.dev/api/v1/orders/id/448291" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupDeliveryTime": "2026-07-07T14:00:00",
    "note": "Customer added items",
    "items": [
      { "productCode": "412009", "quantity": 3, "unitPrice": 4.99 },
      { "productCode": "573301", "quantity": 1, "unitPrice": 6.49 }
    ]
  }'

Response — 200 OK (the updated order)

{
  "orderNumber": "448291",
  "status": "Picking",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "customerId": 18452,
  "externalOrderId": "cart_88213",
  "items": [
    { "productCode": "412009", "quantity": 2, "unitPrice": 4.99 },
    { "productCode": "286748", "quantity": 0, "unitPrice": 12.50, "note": "Out of stock" }
  ],
  "total": 9.98,
  "tracking": {
    "status": "picking",
    "scnNumber": "SCN1043",
    "posOrderId": "448291",
    "invoiceNumber": null,
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "timeline": [
      { "status": "accepted", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "sent_to_pos", "at": "2026-07-06T18:05:09.000Z" },
      { "status": "picking", "at": "2026-07-07T13:10:44.000Z" }
    ]
  }
}

Editable only while status is accepted. After that, 409 order_not_editable: "This order was already sent to the store and can no longer be edited."
The response is the updated order — same shape as GET /orders/id/{orderNumber}; check pickupDeliveryTime and tracking on it.
Sandbox: orders created with a test key are treated as sent immediately, so sandbox edits return order_not_editable — editing is live-only.

Status	Error code	When
200	—	Order updated.
400	invalid_request	A bad items array, an unparseable pickupDeliveryTime, or a priority outside 1–3.
409	order_not_editable	The order was already sent to the store and can no longer be edited.
404	not_found	The order was not created through this API, or does not belong to your organization.
401	unauthorized	Missing or invalid API key.

List & Track Orders

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/orders

Batch tracking for all your orders — the newest 200, each with its normalized status, window, ETA, driver, and full timeline. Poll with since=<your last poll time> every minute or two for cheap incremental updates.

Parameter	In	Type	Required	Description
status	query	string	Optional	Filter by lifecycle status: accepted, sent_to_pos, picking, checked_out, label_created, out_for_delivery, delivered, or cancelled.
date	query	string	Optional	Filter by delivery date, YYYY-MM-DD.
since	query	string	Optional	ISO 8601 instant — return only orders whose tracking changed after it. Pass your last poll time for cheap incremental updates.

statusquerystringOptional: Filter by lifecycle status: accepted, sent_to_pos, picking, checked_out, label_created, out_for_delivery, delivered, or cancelled.
datequerystringOptional: Filter by delivery date, YYYY-MM-DD.
sincequerystringOptional: ISO 8601 instant — return only orders whose tracking changed after it. Pass your last poll time for cheap incremental updates.

Request

curl "https://api.filld.dev/api/v1/orders?since=2026-07-07T13:00:00Z" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "orders": [
    {
      "orderNumber": "448291",
      "externalOrderId": "cart_88213",
      "scnNumber": "SCN1043",
      "posOrderId": "448291",
      "invoiceNumber": "774612",
      "orderMethod": "Delivery",
      "status": "out_for_delivery",
      "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
      "scheduledTime": "2026-07-07T09:00:00",
      "slotOverride": null,
      "priority": 1,
      "itemCount": 12,
      "eta": "2026-07-07T14:42:00.000Z",
      "driver": "Moshe",
      "trackUrl": "https://filld.link/t/8f2ac91d",
      "deliveredAt": null,
      "timeline": [
        { "status": "accepted", "at": "2026-07-06T18:02:11.000Z" },
        { "status": "sent_to_pos", "at": "2026-07-06T18:05:09.000Z" },
        { "status": "picking", "at": "2026-07-07T11:10:44.000Z" },
        { "status": "checked_out", "at": "2026-07-07T12:20:03.000Z" },
        { "status": "label_created", "at": "2026-07-07T12:41:27.000Z" },
        { "status": "out_for_delivery", "at": "2026-07-07T13:05:12.000Z" }
      ],
      "editedAt": null,
      "createdAt": "2026-07-06T18:02:11.000Z",
      "updatedAt": "2026-07-07T13:05:12.000Z"
    }
  ]
}

Statuses update within about 5 minutes of store-side changes; delivery milestones within about 3 minutes. A timeline entry is appended on every transition.
slotOverride is set when the order was accepted outside the normal schedule ("deadline" | "unscheduled" | "uncovered", or combined; older rows may read "full"). priority (1 | 2 | 3, 1 = highest) is present only when it was set on the order. eta, driver, and trackUrl fill in once the order is out for delivery.
Reference ids: scnNumber — our internal order reference (e.g. "SCN1043"), assigned when the order is accepted; useful when talking to the store about an order. posOrderId — the fulfillment system's order id, present once the order has been sent (for orders accepted while held it can differ from your orderNumber — your orderNumber never changes). invoiceNumber — the invoice id, present once the order is checked out.
Sandbox: tracking works with a test key but stays at sent_to_pos — there is no real fulfillment.

Status	Error code	When
200	—	Orders returned (newest 200).
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

Batch Tracking

Auth: x-api-key

POSThttps://api.filld.dev/api/v1/orders/batch

Batch order tracking by id. Send up to 200 ids — matched against the order number, the SCN number, or your externalOrderId, mixed freely — and get back exactly those orders, in the same row shape as GET /api/v1/orders.

Parameter	In	Type	Required	Description
orderIds	body	array of strings	Required	Up to 200 ids, matched against the order number, the SCN number, or your externalOrderId — mix freely.

orderIdsbodyarray of stringsRequired: Up to 200 ids, matched against the order number, the SCN number, or your externalOrderId — mix freely.

Request

curl -X POST "https://api.filld.dev/api/v1/orders/batch" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "orderIds": ["94021133", "SCN1043", "cart_88213"]
  }'

Response — 200 OK

{
  "orders": [
    {
      "orderNumber": "448291",
      "externalOrderId": "cart_88213",
      "scnNumber": "SCN1043",
      "posOrderId": "448291",
      "invoiceNumber": "774612",
      "orderMethod": "Delivery",
      "status": "out_for_delivery",
      "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
      "scheduledTime": "2026-07-07T09:00:00",
      "slotOverride": null,
      "itemCount": 12,
      "eta": "2026-07-07T14:42:00.000Z",
      "driver": "Moshe",
      "trackUrl": "https://filld.link/t/8f2ac91d",
      "deliveredAt": null,
      "timeline": [
        { "status": "accepted", "at": "2026-07-06T18:02:11.000Z" },
        { "status": "sent_to_pos", "at": "2026-07-06T18:05:09.000Z" },
        { "status": "picking", "at": "2026-07-07T11:10:44.000Z" },
        { "status": "checked_out", "at": "2026-07-07T12:20:03.000Z" },
        { "status": "label_created", "at": "2026-07-07T12:41:27.000Z" },
        { "status": "out_for_delivery", "at": "2026-07-07T13:05:12.000Z" }
      ],
      "editedAt": null,
      "createdAt": "2026-07-06T18:02:11.000Z",
      "updatedAt": "2026-07-07T13:05:12.000Z"
    },
    {
      "orderNumber": "94021133",
      "externalOrderId": null,
      "scnNumber": "SCN1044",
      "posOrderId": null,
      "invoiceNumber": null,
      "orderMethod": "Delivery",
      "status": "accepted",
      "window": { "date": "2026-07-08", "start": "14:00", "end": "17:00" },
      "scheduledTime": "2026-07-08T14:00:00",
      "slotOverride": null,
      "itemCount": 4,
      "eta": null,
      "driver": null,
      "trackUrl": null,
      "deliveredAt": null,
      "timeline": [
        { "status": "accepted", "at": "2026-07-07T15:12:40.000Z" }
      ],
      "editedAt": null,
      "createdAt": "2026-07-07T15:12:40.000Z",
      "updatedAt": "2026-07-07T15:12:40.000Z"
    }
  ]
}

Ids that don't match anything are simply absent from the response — no error. An order referenced by two of its ids returns once (in the example, "SCN1043" and "cart_88213" both reference order 448291, so three ids return two rows).

Status	Error code	When
200	—	Matching orders returned; ids that match nothing are simply absent.
400	invalid_request	orderIds missing, empty, containing non-strings, or more than 200 ids.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Too many requests.

Get Order Status

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/orders/id/{orderNumber}

Fetch an order by its order number. The response reflects the order as it stands — after picking, items reflect what was actually filled.

Parameter	In	Type	Required	Description
orderNumber	path	string	Required	The order number from the create response's Location header.

orderNumberpathstringRequired: The order number from the create response's Location header.

Request

curl "https://api.filld.dev/api/v1/orders/id/448291" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "orderNumber": "448291",
  "status": "Picking",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "customerId": 18452,
  "externalOrderId": "cart_88213",
  "items": [
    { "productCode": "412009", "quantity": 2, "unitPrice": 4.99 },
    { "productCode": "286748", "quantity": 0, "unitPrice": 12.50, "note": "Out of stock" }
  ],
  "total": 9.98,
  "tracking": {
    "status": "picking",
    "scnNumber": "SCN1043",
    "posOrderId": "448291",
    "invoiceNumber": null,
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "timeline": [
      { "status": "accepted", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "sent_to_pos", "at": "2026-07-06T18:05:09.000Z" },
      { "status": "picking", "at": "2026-07-07T13:10:44.000Z" }
    ]
  }
}

Only orders created through this API resolve.
The response includes a tracking object — normalized status, scnNumber, posOrderId, invoiceNumber, eta, driver, trackUrl, receiptUrl, deliveredAt, and the full timeline (see List & Track Orders).
Sandbox: a TEST- id returns a stub order: { id, externalOrderId, status: "OrderEntered", pickupDeliveryTime, items: [], sandbox: true }. Test and live data are isolated — cross-mode lookups return 404.
Errors on this endpoint use the problem+json format.

Status	Error code	When
200	—	The order as it currently stands.
404	not_found	The order was not created through this API, or does not belong to your organization.
502	pos_unreachable	The order could not be retrieved right now. Safe to retry.
401	unauthorized	Missing or invalid API key.

Lookup by External Id

Auth: x-api-key

GEThttps://api.filld.dev/api/v1/orders/external/{externalOrderId}

Fetch an order by your own externalOrderId — the value you sent on the create call. Identical response shape to the id lookup.

Parameter	In	Type	Required	Description
externalOrderId	path	string	Required	Your order id, as sent in the create body's externalOrderId field.

externalOrderIdpathstringRequired: Your order id, as sent in the create body's externalOrderId field.

Request

curl "https://api.filld.dev/api/v1/orders/external/cart_88213" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "orderNumber": "448291",
  "status": "Picking",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "customerId": 18452,
  "externalOrderId": "cart_88213",
  "items": [
    { "productCode": "412009", "quantity": 2, "unitPrice": 4.99 },
    { "productCode": "286748", "quantity": 0, "unitPrice": 12.50, "note": "Out of stock" }
  ],
  "total": 9.98,
  "tracking": {
    "status": "picking",
    "scnNumber": "SCN1043",
    "posOrderId": "448291",
    "invoiceNumber": null,
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "timeline": [
      { "status": "accepted", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "sent_to_pos", "at": "2026-07-06T18:05:09.000Z" },
      { "status": "picking", "at": "2026-07-07T13:10:44.000Z" }
    ]
  }
}

Only orders created through this API resolve.
The response includes a tracking object — normalized status, scnNumber, posOrderId, invoiceNumber, eta, driver, trackUrl, receiptUrl, deliveredAt, and the full timeline (see List & Track Orders).
Errors on this endpoint use the problem+json format.

Status	Error code	When
200	—	The order as it currently stands.
404	not_found	No order with that externalOrderId was created through this API by your organization.
502	pos_unreachable	The order could not be retrieved right now. Safe to retry.
401	unauthorized	Missing or invalid API key.