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

Send orders to Evergreen — same request shape as the POS create-order API. Evergreen picks them, then checks them out on your account.

7 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

Send orders to Evergreen — same request shape as the POS create-order API. Evergreen picks them, then checks them out on your account.

Send an Order

Auth: x-api-key

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

Create an order. Evergreen's own shoppers pick it in the store; when picking is finished it is checked out at the register on your account. Returns 201 Created with an empty body and a Location header carrying the order number.

Header	Required	Description
x-api-key	Required	Your API key.
X-Customer-Pin	Required	The PIN of your on-account customer (customerId). It authorizes the on-account charge when the picked order is checked out. Evergreen keeps it encrypted until then and deletes it right after.
Content-Type	Required	application/json.

Parameter	In	Type	Required	Description
customerId	body	string (≤8 chars)	Required	Your on-account customer id. Every order is billed on account to it (payment method OnAccount).
customer	body	object	Optional	Not used for billing. firstName / lastName / phone are used for the recipient only when deliveryAddress.name / phoneNumber are missing.
externalOrderId	body	string (≤20 chars)	Optional	Your own order reference; must be unique per order. Used by GET /orders/external/{externalOrderId}. If you send the same externalOrderId twice, you get 409 duplicate_order and no second order is created.
items	body	array	Required	Order lines. Must be non-empty, at most 200.
items[].productCode	body	string (≤12 chars)	Required	The item's barcode or item code (PLU). It must be an item the fulfilling store carries. Otherwise the whole order is rejected with 422 unknown_items, which names the codes.
items[].quantity	body	number	Required	A count of units. For a by-weight line (unitOfMeasure "Lbs"), the weight in pounds.
items[].unitOfMeasure	body	string	Optional	"Lbs" for a by-weight line; anything else ("Unit", "Case") is a count.
items[].description	body	string (≤30 chars)	Optional	Line description. Kept for reference only; the store uses its own item names.
items[].unitPrice / totalPrice / priceQty	body	number	Optional	Accepted so existing payloads keep working, and stored for audit. They are NOT used for billing: Evergreen prices every line at the store's regular shelf price (see notes).
items[].note	body	string	Optional	Line note, visible to the shopper.
deliveryAddress	body	object	Delivery	The recipient of the order.
deliveryAddress.name	body	string	Optional	Recipient name. It is printed on the order and the delivery label.
deliveryAddress.phoneNumber	body	string	Optional	Recipient phone, for the driver. Evergreen does not text or email the recipient.
deliveryAddress.address	body	object	Delivery	addressLine1 (≤30 chars), addressLine2, city, state, zipCode. It must be inside our delivery area; otherwise you get 422 address_not_covered.
orderMethod	body	string	Optional	"Pickup" or "Delivery". Defaults to Delivery when deliveryAddress is present.
pickupDeliveryTime	body	string	Conditional	ISO 8601 date-time, Eastern time. This is the requested delivery date and time; the date cannot be in the past. The order goes into the delivery window that covers this time. If no window covers it, it goes into the next window later that same day. If there is none, it is accepted as requested and you get a warning. Window capacity is not checked. Required for Delivery orders without a reservationId.
deliveryWindow	body	object	Optional	Evergreen extension: { "start": "HH:MM", "end": "HH:MM" } (store time). Use it to name the window yourself. It is accepted as sent; the date still comes from pickupDeliveryTime.
note	body	string	Optional	Order-level note, shown to the store.
payment / paymentEndpoint	body	object	Optional	Ignored. Orders are always billed OnAccount to customerId with the X-Customer-Pin you send. No payment webhook is called.
priority	body	integer	Optional	Evergreen extension: 1 \| 2 \| 3 (1 = highest; omitted = normal). Higher-priority orders are picked first. Other values return 400 invalid_request.
reservationId	body	string	Optional	Evergreen extension, optional: attach a slot you reserved earlier (res_…). The order takes that reservation's window, and the reservation is confirmed. You do not need a reservation to send an order.
store	body	string	Optional	Evergreen extension, pickup orders only: the fulfilling store, e.g. "uptown". Delivery orders are routed by address.

customerIdbodystring (≤8 chars)Required: Your on-account customer id. Every order is billed on account to it (payment method OnAccount).
customerbodyobjectOptional: Not used for billing. firstName / lastName / phone are used for the recipient only when deliveryAddress.name / phoneNumber are missing.
externalOrderIdbodystring (≤20 chars)Optional: Your own order reference; must be unique per order. Used by GET /orders/external/{externalOrderId}. If you send the same externalOrderId twice, you get 409 duplicate_order and no second order is created.
itemsbodyarrayRequired: Order lines. Must be non-empty, at most 200.
items[].productCodebodystring (≤12 chars)Required: The item's barcode or item code (PLU). It must be an item the fulfilling store carries. Otherwise the whole order is rejected with 422 unknown_items, which names the codes.
items[].quantitybodynumberRequired: A count of units. For a by-weight line (unitOfMeasure "Lbs"), the weight in pounds.
items[].unitOfMeasurebodystringOptional: "Lbs" for a by-weight line; anything else ("Unit", "Case") is a count.
items[].descriptionbodystring (≤30 chars)Optional: Line description. Kept for reference only; the store uses its own item names.
items[].unitPrice / totalPrice / priceQtybodynumberOptional: Accepted so existing payloads keep working, and stored for audit. They are NOT used for billing: Evergreen prices every line at the store's regular shelf price (see notes).
items[].notebodystringOptional: Line note, visible to the shopper.
deliveryAddressbodyobjectDelivery: The recipient of the order.
deliveryAddress.namebodystringOptional: Recipient name. It is printed on the order and the delivery label.
deliveryAddress.phoneNumberbodystringOptional: Recipient phone, for the driver. Evergreen does not text or email the recipient.
deliveryAddress.addressbodyobjectDelivery: addressLine1 (≤30 chars), addressLine2, city, state, zipCode. It must be inside our delivery area; otherwise you get 422 address_not_covered.
orderMethodbodystringOptional: "Pickup" or "Delivery". Defaults to Delivery when deliveryAddress is present.
pickupDeliveryTimebodystringConditional: ISO 8601 date-time, Eastern time. This is the requested delivery date and time; the date cannot be in the past. The order goes into the delivery window that covers this time. If no window covers it, it goes into the next window later that same day. If there is none, it is accepted as requested and you get a warning. Window capacity is not checked. Required for Delivery orders without a reservationId.
deliveryWindowbodyobjectOptional: Evergreen extension: { "start": "HH:MM", "end": "HH:MM" } (store time). Use it to name the window yourself. It is accepted as sent; the date still comes from pickupDeliveryTime.
notebodystringOptional: Order-level note, shown to the store.
payment / paymentEndpointbodyobjectOptional: Ignored. Orders are always billed OnAccount to customerId with the X-Customer-Pin you send. No payment webhook is called.
prioritybodyintegerOptional: Evergreen extension: 1 | 2 | 3 (1 = highest; omitted = normal). Higher-priority orders are picked first. Other values return 400 invalid_request.
reservationIdbodystringOptional: Evergreen extension, optional: attach a slot you reserved earlier (res_…). The order takes that reservation's window, and the reservation is confirmed. You do not need a reservation to send an order.
storebodystringOptional: Evergreen extension, pickup orders only: the fulfilling store, e.g. "uptown". Delivery orders are routed by address.

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"
      },
      {
        "productCode": "286748",
        "description": "Chicken Cutlets",
        "quantity": 3.5,
        "unitOfMeasure": "Lbs",
        "note": "Sliced thin, please"
      }
    ],
    "deliveryAddress": {
      "name": "Chaim Brachfeld",
      "phoneNumber": "8455550142",
      "address": {
        "addressLine1": "12 Main St",
        "city": "Monsey",
        "state": "NY",
        "zipCode": "10952"
      }
    },
    "priority": 2,
    "note": "Leave by the side door"
  }'

Response — 201 Created (empty body)

HTTP/1.1 201 Created
Location: /orders/id/SCN1254
x-evergreen-delivery-time: 2026-07-07T12:00:00-04:00
x-evergreen-store: monsey
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 and use your Evergreen x-api-key. The request body, the 201 + Location response and the error format (RFC 7807 problem+json) are the same as the POS API's.
What happens to the order: it goes into Evergreen's picking queue, not straight to the POS. Our shoppers pick it in the store. When picking is finished, it is entered in the POS as picked, checked out on account to your customerId (OnAccount, authorized with your X-Customer-Pin), labeled and delivered. Follow each step in the order's status (see List & Track Orders).
The Location header carries your order number, your Evergreen reference (e.g. SCN1254). It is the number the store uses and it never changes. The order has a POS order id (posOrderId) only after it is checked out.
Pricing: every line is billed at the fulfilling store's REGULAR shelf price. Sale prices, multi-buy ("2 for") and case prices are never applied, and nothing is added on top. Prices you send are ignored (kept for audit). By-weight lines are billed by the weight actually picked. The receipt shows what the register actually charged.
Account fees: if Evergreen has set up fees or standard items for your account (for example a handling fee or bags), they are added to every order automatically. Item lines are picked with the order; fee lines are charged at checkout. Both appear on the POS order and on the receipt.
Substitutions (SCN orders): if an item is out of stock, the shopper may substitute a similar item at the same price or cheaper (at most 5% more). The recipient is not contacted. Substitutes and items not found are listed on the receipt.
Slots are not booked: the requested date and time are accepted without a capacity check. We only check that the address is in our delivery area (422 address_not_covered), that the date is not in the past (422 invalid_delivery_date) and that the time is valid (400). A reservation (reservationId) is optional; reservations still work if you use them.
If no delivery window covers the requested time on that date, the order is still accepted (201). You also get an x-evergreen-warning header and a JSON body (warning "no_matching_window"); the store will confirm the time.
Optional Evergreen extensions: deliveryWindow — name the window yourself; reservationId — use a slot you reserved earlier; store — pickup orders only; priority — 1 | 2 | 3 (1 = highest). A standard payload works without them.
Unknown items: if any productCode is not an item the fulfilling store carries, the whole order is rejected with 422 unknown_items, which lists the codes. Nothing is created; fix the codes and send the order again.
Hold for review (set by Evergreen per partner): the order is accepted the same way but stays at status accepted until the store releases it into picking. You can edit it until then.
Sandbox: orders created with a test key are not placed or picked. You receive a TEST-prefixed order number (Location: /orders/id/TEST-48210937, plus x-evergreen-sandbox: true). Validation is lighter than live.
Sandbox failure simulation: include the string simulate=pos_error anywhere in note to receive a 400 in the standard problem+json format.

Status	Error code	When
201	—	Order created — empty body; the Location header carries the order number.
400	invalid_request	The body is malformed: no items, a line without productCode or a positive quantity, a missing customerId, a delivery order without a valid pickupDeliveryTime, or a bad deliveryWindow / priority.
409	duplicate_order	An order with this externalOrderId was already received. The original stands; no second order was created.
409	reservation_expired / reservation_cancelled	The reservationId you sent no longer holds a slot. Send the order without it, or reserve again.
422	address_not_covered	The delivery address is outside our delivery area.
422	invalid_delivery_date	The requested date is in the past.
422	unknown_items	One or more productCodes are not sold at the fulfilling store (the codes are listed). Nothing was created.
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 (held for review, not yet released to picking). 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 to another date/window. Same rules as create (address in area, date not past; no capacity check).
deliveryWindow	body	object	Optional	{ "start": "HH:MM", "end": "HH:MM" } — name the window yourself, as on create.
deliveryAddress	body	object	Optional	Merged into the order's address (partial updates are fine); the window is worked out again for the new address.
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 to another date/window. Same rules as create (address in area, date not past; no capacity check).
deliveryWindowbodyobjectOptional: { "start": "HH:MM", "end": "HH:MM" } — name the window yourself, as on create.
deliveryAddressbodyobjectOptional: Merged into the order's address (partial updates are fine); the window is worked out again for the new address.
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/SCN1043" \
  -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 },
      { "productCode": "573301", "quantity": 1 }
    ]
  }'

Response — 200 OK (the updated order)

{
  "id": "SCN1043",
  "externalOrderId": "cart_88213",
  "status": "Picked",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "items": [
    { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "totalPrice": 9.98, "pickStatus": "picked" },
    { "productCode": "4011", "description": "Bananas", "quantity": 2, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "totalPrice": 1.58, "pickStatus": "picked" },
    { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1, "unitOfMeasure": "Unit", "unitPrice": 6.49, "totalPrice": 6.49, "pickStatus": "not_found" }
  ],
  "deliveryAddress": {
    "name": "Chana Cohen",
    "phoneNumber": "8455551234",
    "address": { "addressLine1": "12 Maple Ave", "city": "Monsey", "state": "NY", "zipCode": "10952" }
  },
  "tracking": {
    "status": "picking_finished",
    "scnNumber": "SCN1043",
    "posOrderId": null,
    "invoiceNumber": null,
    "store": "monsey",
    "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "photoUrl": null,
    "photo2Url": null,
    "signatureUrl": null,
    "proofUrl": null,
    "receiptReady": true,
    "timeline": [
      { "status": "received", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "picking_started", "at": "2026-07-07T08:10:44.000Z" },
      { "status": "picking_finished", "at": "2026-07-07T08:31:02.000Z" }
    ]
  },
  "receipt": {
    "orderNumber": "SCN1043",
    "scnNumber": "SCN1043",
    "externalOrderId": "cart_88213",
    "posOrderId": "1630X",
    "posInvoiceNumber": "611234567",
    "posStatus": "Done",
    "store": { "slug": "monsey", "name": "Evergreen Monsey" },
    "delivery": { "method": "Delivery", "date": "2026-07-07", "window": { "start": "09:00", "end": "12:00" } },
    "recipient": { "name": "Chana Cohen", "phone": "+18455551234", "address": "12 Maple Ave, Monsey, NY 10952" },
    "lines": [
      { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "lineTotal": 9.98, "ordered": { "quantity": 2, "weightLb": null, "description": "Whole Milk 1 Gal" } },
      { "productCode": "4011", "description": "Bananas", "quantity": 1.84, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "lineTotal": 1.45, "ordered": { "quantity": 1, "weightLb": 2, "description": "Bananas" } }
    ],
    "notCharged": [
      { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1 }
    ],
    "subtotal": 11.43,
    "fees": [
      { "label": "Handling fee", "productCode": "301", "amount": 2.5 }
    ],
    "total": 13.93,
    "currency": "USD",
    "pdfUrl": "https://api.filld.dev/api/v1/orders/id/SCN1043/receipt",
    "generatedAt": "2026-07-07T08:35:00.000Z"
  }
}

Editable only while status is accepted, which happens only when your organization's orders are held for review. Orders that go straight into picking (status received) cannot be edited and return 409 order_not_editable: "This order was already sent to the store and can no longer be edited."
Items are priced again at the regular shelf price, and unknown codes are rejected (422 unknown_items), as on create.
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

Tracking for all your orders: the newest 200, each with its status, window, ETA, driver, delivery proof and full timeline. To follow specific orders, use Batch Tracking.

Parameter	In	Type	Required	Description
status	query	string	Optional	Filter by lifecycle status: accepted, received, picking_started, picking_finished, sent_to_pos, 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, received, picking_started, picking_finished, sent_to_pos, 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": "SCN1043",
      "scnNumber": "SCN1043",
      "posOrderId": "448291",
      "invoiceNumber": "774612",
      "externalOrderId": "cart_88213",
      "orderMethod": "Delivery",
      "status": "out_for_delivery",
      "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
      "scheduledTime": "2026-07-07T12:00:00-04:00",
      "priority": 1,
      "itemCount": 12,
      "eta": "2026-07-07T14:42:00.000Z",
      "driver": "Moshe",
      "trackUrl": "https://filld.link/t/8f2ac91d",
      "deliveredAt": null,
      "photoUrl": null,
      "photo2Url": null,
      "signatureUrl": null,
      "proofUrl": null,
      "receiptUrl": null,
      "receiptReady": true,
      "timeline": [
        { "status": "received", "at": "2026-07-06T18:02:11.000Z" },
        { "status": "picking_started", "at": "2026-07-07T08:10:44.000Z" },
        { "status": "picking_finished", "at": "2026-07-07T08:31:02.000Z" },
        { "status": "sent_to_pos", "at": "2026-07-07T08:31:05.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, in order: accepted (held for review, only if your orders are held) → received (in our picking queue) → picking_started → picking_finished (picked and packed) → sent_to_pos (entered in the POS as picked) → checked_out (charged on your account at the register; the receipt is ready) → label_created → out_for_delivery → delivered. cancelled can happen at any point before delivery.
timeline lists every step the order reached, each with its time. eta, driver and trackUrl appear once the order is out for delivery. When it is delivered you also get photoUrl, photo2Url, signatureUrl, proofUrl (the proof-of-delivery page) and receiptUrl (the signed delivery receipt), when the driver captured them.
receiptReady turns true once the order is checked out at the register. From then on, the order detail (GET /orders/id/{orderNumber}) has a receipt object — what the POS actually charged — and the printable receipt is at its pdfUrl.
How fresh: picking steps show right away. The POS checkout (checked_out) and the delivery steps are checked every few minutes, so expect a delay of up to about 5 minutes.
Reference ids: orderNumber (= scnNumber, e.g. "SCN1043") is your Evergreen order number and never changes. posOrderId is the POS order id, present once the order is in the POS. invoiceNumber is present once the order is checked out.
slotOverride is set when the order was accepted outside a normal delivery window ("unscheduled" | "deadline"). priority (1 | 2 | 3, 1 = highest) is present only when it was set.
Sandbox: tracking works with a test key but stays at sent_to_pos, because sandbox orders are not picked.

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": ["SCN1043", "cart_88213", "cart_88240"]
  }'

Response — 200 OK

{
  "orders": [
    {
      "orderNumber": "SCN1043",
      "scnNumber": "SCN1043",
      "posOrderId": "448291",
      "invoiceNumber": "774612",
      "externalOrderId": "cart_88213",
      "orderMethod": "Delivery",
      "status": "delivered",
      "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
      "scheduledTime": "2026-07-07T12:00:00-04:00",
      "itemCount": 12,
      "eta": "2026-07-07T14:42:00.000Z",
      "driver": "Moshe",
      "trackUrl": "https://filld.link/t/8f2ac91d",
      "deliveredAt": "2026-07-07T14:39:51.000Z",
      "photoUrl": "https://pod.example.com/p/8f2ac91d-1.jpg",
      "photo2Url": null,
      "signatureUrl": "https://pod.example.com/s/8f2ac91d.png",
      "proofUrl": "https://filld.link/t/8f2ac91d",
      "receiptUrl": "https://pod.example.com/r/8f2ac91d.pdf",
      "receiptReady": true,
      "timeline": [
        { "status": "received", "at": "2026-07-06T18:02:11.000Z" },
        { "status": "picking_started", "at": "2026-07-07T08:10:44.000Z" },
        { "status": "picking_finished", "at": "2026-07-07T08:31:02.000Z" },
        { "status": "sent_to_pos", "at": "2026-07-07T08:31:05.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" },
        { "status": "delivered", "at": "2026-07-07T14:39:51.000Z" }
      ],
      "editedAt": null,
      "createdAt": "2026-07-06T18:02:11.000Z",
      "updatedAt": "2026-07-07T14:41:00.000Z"
    },
    {
      "orderNumber": "SCN1044",
      "scnNumber": "SCN1044",
      "posOrderId": null,
      "invoiceNumber": null,
      "externalOrderId": "cart_88240",
      "orderMethod": "Delivery",
      "status": "received",
      "window": { "date": "2026-07-08", "start": "14:00", "end": "17:00" },
      "scheduledTime": "2026-07-08T17:00:00-04:00",
      "itemCount": 4,
      "eta": null,
      "driver": null,
      "trackUrl": null,
      "deliveredAt": null,
      "photoUrl": null,
      "photo2Url": null,
      "signatureUrl": null,
      "proofUrl": null,
      "receiptUrl": null,
      "receiptReady": false,
      "timeline": [
        { "status": "received", "at": "2026-07-07T15:12:40.000Z" }
      ],
      "editedAt": null,
      "createdAt": "2026-07-07T15:12:40.000Z",
      "updatedAt": "2026-07-07T15:12:40.000Z"
    }
  ]
}

This is the recommended way to poll. Send the ids of your open orders (up to 200 per call) every few minutes, and drop an order from your list once it is delivered or cancelled. Statuses refresh every few minutes, so polling more often than once a minute gains nothing.
Ids that don't match anything are left out of the response; that is not an error. An order matched by two of its ids is returned once. In the example, "SCN1043" and "cart_88213" are the same order, 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: its lines, the tracking block and, once it is checked out, the receipt.

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/SCN1043" \
  -H "x-api-key: evg_live_XXXXXXXXXXXXXXXX"

Response — 200 OK

{
  "id": "SCN1043",
  "externalOrderId": "cart_88213",
  "status": "Picked",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "items": [
    { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "totalPrice": 9.98, "pickStatus": "picked" },
    { "productCode": "4011", "description": "Bananas", "quantity": 2, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "totalPrice": 1.58, "pickStatus": "picked" },
    { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1, "unitOfMeasure": "Unit", "unitPrice": 6.49, "totalPrice": 6.49, "pickStatus": "not_found" }
  ],
  "deliveryAddress": {
    "name": "Chana Cohen",
    "phoneNumber": "8455551234",
    "address": { "addressLine1": "12 Maple Ave", "city": "Monsey", "state": "NY", "zipCode": "10952" }
  },
  "tracking": {
    "status": "picking_finished",
    "scnNumber": "SCN1043",
    "posOrderId": null,
    "invoiceNumber": null,
    "store": "monsey",
    "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "photoUrl": null,
    "photo2Url": null,
    "signatureUrl": null,
    "proofUrl": null,
    "receiptReady": true,
    "timeline": [
      { "status": "received", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "picking_started", "at": "2026-07-07T08:10:44.000Z" },
      { "status": "picking_finished", "at": "2026-07-07T08:31:02.000Z" }
    ]
  },
  "receipt": {
    "orderNumber": "SCN1043",
    "scnNumber": "SCN1043",
    "externalOrderId": "cart_88213",
    "posOrderId": "1630X",
    "posInvoiceNumber": "611234567",
    "posStatus": "Done",
    "store": { "slug": "monsey", "name": "Evergreen Monsey" },
    "delivery": { "method": "Delivery", "date": "2026-07-07", "window": { "start": "09:00", "end": "12:00" } },
    "recipient": { "name": "Chana Cohen", "phone": "+18455551234", "address": "12 Maple Ave, Monsey, NY 10952" },
    "lines": [
      { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "lineTotal": 9.98, "ordered": { "quantity": 2, "weightLb": null, "description": "Whole Milk 1 Gal" } },
      { "productCode": "4011", "description": "Bananas", "quantity": 1.84, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "lineTotal": 1.45, "ordered": { "quantity": 1, "weightLb": 2, "description": "Bananas" } }
    ],
    "notCharged": [
      { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1 }
    ],
    "subtotal": 11.43,
    "fees": [
      { "label": "Handling fee", "productCode": "301", "amount": 2.5 }
    ],
    "total": 13.93,
    "currency": "USD",
    "pdfUrl": "https://api.filld.dev/api/v1/orders/id/SCN1043/receipt",
    "generatedAt": "2026-07-07T08:35:00.000Z"
  }
}

Only orders created through this API resolve.
status uses the POS names your integration already reads: OrderEntered (held), Unpicked (in the queue), InProgress (picking), Picked (packed), then the POS's own status (e.g. Done), or Cancelled. tracking.status gives the exact step (see List & Track Orders).
items are the lines as ordered, priced at the regular shelf price. pickStatus is pending, picked, partial or not_found.
The tracking object has the status, scnNumber, posOrderId, invoiceNumber, store, window, eta, driver, trackUrl, deliveredAt, photoUrl, photo2Url, signatureUrl, proofUrl, receiptUrl, receiptReady and the full timeline.
receipt (null until the order is checked out) is what the register ACTUALLY CHARGED, read back from the POS order: posInvoiceNumber, posStatus, and one line per POS line — productCode, description, quantity (pounds on a "Lbs" line), unitOfMeasure, unitPrice, lineTotal and, when it matches an ordered item, ordered { quantity, weightLb, description }. A substitute appears under its own code. notCharged lists ordered items the POS order doesn't charge for (not found). fees lists your account's fee lines as charged. Then subtotal, total and pdfUrl, the printable receipt (see Get a Receipt).
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	Orders sent before Evergreen picking (read live from the POS) only: the order could not be retrieved right now. Safe to retry.
401	unauthorized	Missing or invalid API key.

Get a Receipt

Auth: x-api-key

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

The printable receipt: what the register actually charged (from the POS order), next to what was ordered, with items not charged and your account fees. Available once the order is checked out.

Parameter	In	Type	Required	Description
orderNumber	path	string	Required	The order number (SCN…).
format	query	string	Optional	"json" returns the receipt object (the same one as on the order detail) instead of the page.

orderNumberpathstringRequired: The order number (SCN…).
formatquerystringOptional: "json" returns the receipt object (the same one as on the order detail) instead of the page.

Request

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

Response — 200 OK (text/html — a print-ready page)

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

Returns a self-contained, print-friendly HTML page. To get a PDF, print it and choose Save as PDF, or render it with any HTML-to-PDF tool. Send your x-api-key header to fetch it; the receipt's pdfUrl points here.
Prices are what is billed: regular shelf prices, by-weight lines at the weight picked. The total matches what was checked out on your account.

Status	Error code	When
200	—	The receipt page (or JSON with format=json).
409	receipt_not_ready	Picking isn't finished yet.
404	not_found	No such order for your organization, or an order sent before Evergreen picking (those have no receipt).
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

{
  "id": "SCN1043",
  "externalOrderId": "cart_88213",
  "status": "Picked",
  "orderMethod": "Delivery",
  "pickupDeliveryTime": "2026-07-07T12:00:00-04:00",
  "items": [
    { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "totalPrice": 9.98, "pickStatus": "picked" },
    { "productCode": "4011", "description": "Bananas", "quantity": 2, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "totalPrice": 1.58, "pickStatus": "picked" },
    { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1, "unitOfMeasure": "Unit", "unitPrice": 6.49, "totalPrice": 6.49, "pickStatus": "not_found" }
  ],
  "deliveryAddress": {
    "name": "Chana Cohen",
    "phoneNumber": "8455551234",
    "address": { "addressLine1": "12 Maple Ave", "city": "Monsey", "state": "NY", "zipCode": "10952" }
  },
  "tracking": {
    "status": "picking_finished",
    "scnNumber": "SCN1043",
    "posOrderId": null,
    "invoiceNumber": null,
    "store": "monsey",
    "window": { "date": "2026-07-07", "start": "09:00", "end": "12:00" },
    "eta": null,
    "driver": null,
    "trackUrl": null,
    "receiptUrl": null,
    "deliveredAt": null,
    "photoUrl": null,
    "photo2Url": null,
    "signatureUrl": null,
    "proofUrl": null,
    "receiptReady": true,
    "timeline": [
      { "status": "received", "at": "2026-07-06T18:02:11.000Z" },
      { "status": "picking_started", "at": "2026-07-07T08:10:44.000Z" },
      { "status": "picking_finished", "at": "2026-07-07T08:31:02.000Z" }
    ]
  },
  "receipt": {
    "orderNumber": "SCN1043",
    "scnNumber": "SCN1043",
    "externalOrderId": "cart_88213",
    "posOrderId": "1630X",
    "posInvoiceNumber": "611234567",
    "posStatus": "Done",
    "store": { "slug": "monsey", "name": "Evergreen Monsey" },
    "delivery": { "method": "Delivery", "date": "2026-07-07", "window": { "start": "09:00", "end": "12:00" } },
    "recipient": { "name": "Chana Cohen", "phone": "+18455551234", "address": "12 Maple Ave, Monsey, NY 10952" },
    "lines": [
      { "productCode": "041303001233", "description": "Whole Milk 1 Gal", "quantity": 2, "unitOfMeasure": "Unit", "unitPrice": 4.99, "lineTotal": 9.98, "ordered": { "quantity": 2, "weightLb": null, "description": "Whole Milk 1 Gal" } },
      { "productCode": "4011", "description": "Bananas", "quantity": 1.84, "unitOfMeasure": "Lbs", "unitPrice": 0.79, "lineTotal": 1.45, "ordered": { "quantity": 1, "weightLb": 2, "description": "Bananas" } }
    ],
    "notCharged": [
      { "productCode": "286748", "description": "Tahini 16 oz", "quantity": 1 }
    ],
    "subtotal": 11.43,
    "fees": [
      { "label": "Handling fee", "productCode": "301", "amount": 2.5 }
    ],
    "total": 13.93,
    "currency": "USD",
    "pdfUrl": "https://api.filld.dev/api/v1/orders/id/SCN1043/receipt",
    "generatedAt": "2026-07-07T08:35:00.000Z"
  }
}

Only orders created through this API resolve.
Same response as Get Order Status: the lines, the tracking object (status, timeline and delivery proof) and the receipt once it is checked out.
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.