Provider Orders

Function-calling namespace: providerOrders

Base URL: https://api.aivida.in
Engine endpoint: POST /api
Auth: Stack token middleware enabled in optional mode.
Send token in header: x-stack-access-token: <access_token> (or Authorization: Bearer <access_token>).
In optional mode: no token is allowed; invalid token is rejected with 401.

Shadowfax Fulfillment Modes

Provider order serviceability supports two Shadowfax flows. The active flow is controlled by the Super Admin platformSettings.updateShadowfaxFlow API. If no platform setting has been saved yet, the backend falls back to SHADOWFAX_FLOW, whose default is on_demand.

Use platformSettings.getShadowfaxFlow to read which flow is already selected:

{
  "namespace": "platformSettings",
  "apiName": "getShadowfaxFlow",
  "data": {}
}

Use platformSettings.updateShadowfaxFlow to switch the active flow:

{
  "namespace": "platformSettings",
  "apiName": "updateShadowfaxFlow",
  "data": {
    "flow": "on_demand",
    "updatedBy": "user_123"
  }
}

updatedBy should be the logged-in Super Admin user ID when available. It is optional and can also be a string audit label.

Flow	Setting value	Shadowfax API used by backend	Pickup model
On demand	`on_demand` (default)	Serviceability: `POST /api/v1/order-serviceability/`; create order: `POST /api/v2/orders/`; edit order: `PUT /api/v2/orders/{sfx_order_id}/edit/`; cancel: `PUT /api/v2/orders/{sfx_order_id}/cancel/`	Dynamic pickup coordinates from the organization
Dedicated / store-based	`dedicated`	Serviceability: `PUT /api/v2/store_serviceability/`; create order: `POST /api/v2/stores/orders/`; edit order: `PUT /api/v1/stores/edit-order/`; cancel: `PUT /api/v2/orders/{sfx_order_id}/cancel/`	Fixed Shadowfax store code from organization settings

Dedicated mode expects each organization to have a Shadowfax store code configured in organization settings. On-demand mode uses the organization’s coordinates.latitude and coordinates.longitude as pickup coordinates and the order delivery address coordinates as drop coordinates.

Order and Fulfillment Status Synchronization

Provider orders expose the customer-facing lifecycle. Fulfillments store logistics/provider events from Shadowfax and future delivery providers.

Provider Order Status Values

Use uppercase enum-style values:

PENDING
CONFIRMED
PACKING
READY_FOR_DISPATCH
OUT_FOR_DELIVERY
DELIVERED
CANCELLED

The backend accepts lowercase, hyphenated, or spaced status payloads and filters, then normalizes them before storing/querying.

Fulfillment Status Values

PENDING
ORDER_CREATED
ASSIGNED
READY_FOR_DISPATCH
PICKED_UP
OUT_FOR_DELIVERY
DELIVERED
FAILED
RETRYING
CANCELLED

Fulfillment to Order

Only business milestones update the customer-facing provider order:

Fulfillment status	Provider order status
`READY_FOR_DISPATCH`	`READY_FOR_DISPATCH`
`PICKED_UP`	`OUT_FOR_DELIVERY`
`OUT_FOR_DELIVERY`	`OUT_FOR_DELIVERY`
`DELIVERED`	`DELIVERED`
`CANCELLED`	`CANCELLED`

Technical fulfillment statuses such as PENDING, ORDER_CREATED, ASSIGNED, FAILED, and RETRYING stay internal and do not change patient-facing order status.

Manual Order Updates

PACKING: updates only the provider order.
READY_FOR_DISPATCH: updates provider order and fulfillment; Shadowfax dispatch-ready is triggered when available.
OUT_FOR_DELIVERY: normally comes from provider events, but admin override is allowed.
DELIVERED: updates provider order and fulfillment, sets delivered timestamps, and creates a manual completion audit log.
CANCELLED: updates provider order and fulfillment, and calls provider cancellation when supported.

`checkServiceability`

Source: backend/endpoints/provider-orders/check-serviceability

Use this API before creating/fulfilling a provider order.

Input Fields

Field	Type	Required	Notes
`organizationIds`	`array<string>`	Yes	One or more provider organization IDs. `organization_id` / `organizationId` is also accepted for a single organization.
`delivery_address`	`object`	Yes	Must include `latitude` and `longitude`. `deliveryAddress` is also accepted.
`COID`	`string`	No	On-demand client order ID sent to Shadowfax. Generated if omitted.
`paid`	`boolean` or `"true"` / `"false"`	No	On-demand payment flag. Defaults to `false`.
`stage_of_check`	`string`	No	On-demand stage. Defaults to `post_order`.
`order_value`	`number`	No	On-demand order value sent to Shadowfax.
`rain_flag`	`boolean`	No	On-demand rain-impact flag.
`client_surge`	`number`	No	On-demand client surge amount.

On-Demand Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "checkServiceability",
  "data": {
    "organizationIds": ["org_123"],
    "delivery_address": {
      "latitude": 12.897338,
      "longitude": 77.552905
    },
    "COID": "order_23434",
    "paid": false,
    "stage_of_check": "post_order",
    "order_value": 250,
    "rain_flag": false,
    "client_surge": 0
  }
}'

On-Demand Shadowfax Payload

The backend maps the public request into Shadowfax’s on-demand serviceability API:

{
  "pickup_longitude": 77.5620661,
  "drop_latitude": 12.897338,
  "drop_longitude": 77.552905,
  "pickup_latitude": 12.9276526,
  "paid": "false",
  "COID": "order_23434",
  "stage_of_check": "post_order",
  "order_value": 250,
  "rain_flag": false,
  "client_surge": 0
}

Example Response

{
  "status": "ok",
  "data": {
    "success": true,
    "serviceable": false,
    "delivery_cost": 0,
    "rain_surge_amount": 0,
    "pickup_eta": 0,
    "drop_eta": 0,
    "reason": "Shadowfax on-demand serviceability unavailable"
  }
}

On-Demand Create Order

When a paid/confirmed provider order is sent to Shadowfax with active flow on_demand, the backend calls POST /api/v2/orders/.

Shadowfax Payload

{
  "has_tip": true,
  "tip_amount": 35,
  "order_details": {
    "scheduled_time": "2026-03-12 16:00:00",
    "order_value": 248,
    "paid": "false",
    "client_order_id": "379984400",
    "pickup_otp": "1232",
    "return_otp": "1234",
    "rain_flag": false,
    "delivery_instruction": {
      "drop_instruction_text": "Don't call me. Please come to the first floor and ring the doorbell.",
      "take_drop_off_picture": true,
      "drop_off_picture_mandatory": true,
      "client_surge": 0
    }
  },
  "client_code": "merchant001",
  "pickup_details": {
    "city": "Delhi",
    "contact_number": "9876543210",
    "name": "Store name",
    "longitude": 77.0563207,
    "address": "Store address in plain text",
    "latitude": 28.5833332
  },
  "order_items": [
    {
      "name": "Item name",
      "price": 259,
      "quantity": 3,
      "id": "29656019"
    }
  ],
  "drop_details": {
    "name": "Customer name",
    "longitude": 77.037531,
    "address": "Customer address in plain text",
    "latitude": 28.588891,
    "contact_number": "9987654321",
    "city": "Delhi",
    "delivery_otp": "7412"
  }
}

Shadowfax Response

{
  "message": "Success",
  "data": {
    "client_code": "merchant001",
    "status": "ACCEPTED",
    "sfx_order_id": 20611002,
    "track_url": "http://api.shadowfax.in/track/612DD77D2422061560174C3E685FE7C2/",
    "delivery_cost": 59,
    "order_details": {
      "client_order_id": "379984400",
      "pickup_eta": 12,
      "drop_eta": 20
    }
  }
}

The backend preserves client_code, sfx_order_id, track_url, delivery_cost, and the raw response in fulfillment storage/audit data.

`create`

Source: backend/endpoints/provider-orders/create

Input Fields

Field	Type	Required
`patientProfileId`	`string`	Yes
`organizationId`	`string`	Yes
`sourceType`	`string`	Yes
`prescriptionId`	`string`	No
`labOrderId`	`string`	No
`appointmentId`	`string`	No
`consultationId`	`string`	No
`items`	`[]models.ProviderOrderItem`	Yes
`subtotal`	`float64`	No
`status`	`string`	Yes
`deliveryAddress`	`*models.ProviderOrderDeliveryAddress`	No
`confirmedAt`	`*int64`	No
`packingAt`	`*int64`	No
`dispatchedAt`	`*int64`	No
`outForDeliveryAt`	`*int64`	No
`deliveredAt`	`*int64`	No
`patientNotes`	`string`	No
`providerNotes`	`string`	No
`razorpayOrderId`	`string`	No
`razorpayPaymentId`	`string`	No
`razorpaySignature`	`string`	No
`paymentStatus`	`string`	No
`amountPaid`	`*float64`	No
`paidAt`	`*int64`	No
`paymentMethod`	`string`	No
`checkoutSessionId`	`string`	No
`createdAt`	`*int64`	No
`updatedAt`	`*int64`	No

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "create",
  "data": {
    "patientProfileId": "patientprofile_123",
    "organizationId": "org_123",
    "sourceType": "GENERAL",
    "items": [],
    "status": "ACTIVE"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`delete`

Source: backend/endpoints/provider-orders/delete

Input Fields

Field	Type	Required
`id`	`string`	Yes
`organizationId`	`string`	Yes

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "delete",
  "data": {
    "id": "id_123",
    "organizationId": "org_123"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`getById`

Source: backend/endpoints/provider-orders/get-by-id

Returns a provider order by ID. For Shadowfax orders with externalOrderId set, the backend enriches the response by calling the existing Shadowfax order details API:

GET /api/v2/orders/{sfx_order_id}/status/

The same Shadowfax details path is used for dedicated and on-demand flows. No separate on-demand get-details API is needed. If Shadowfax is unavailable, the order still returns and fulfillment.syncError contains the provider error.

Input Fields

Field	Type	Required
`id`	`string`	Yes
`organizationId`	`string`	Yes

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "getById",
  "data": {
    "id": "id_123",
    "organizationId": "org_123"
  }
}'

Example Response

{
  "status": "ok",
  "data": {
    "_id": "provider_order_123",
    "organizationId": "org_123",
    "externalOrderId": "9260127",
    "fulfillmentProvider": "SHADOWFAX",
    "fulfillment": {
      "provider": "SHADOWFAX",
      "externalOrderId": "20611002",
      "status": "ALLOTTED",
      "trackingUrl": "http://api.shadowfax.in/track/612DD77D2422061560174C3E685FE7C2/",
      "dropImageUrl": "some_url",
      "rider": {
        "name": "Amit Kumar",
        "phone": "9877654321",
        "location": {
          "latitude": 12.932544038808764,
          "longitude": 77.61393159627914
        }
      },
      "eta": {
        "pickupMinutes": 12,
        "dropMinutes": 20
      },
      "pickup": {
        "name": "Store name",
        "phone": "9876543210",
        "address": "Store address in plain text",
        "city": "Delhi",
        "latitude": 28.5833332,
        "longitude": 77.0563207
      },
      "drop": {
        "name": "Customer name",
        "address": "Customer address in plain text",
        "city": "Delhi",
        "latitude": 28.588891,
        "longitude": 77.037531
      },
      "providerItems": [
        {
          "id": "29656019",
          "name": "Item name",
          "quantity": 3,
          "price": 259,
          "unitPrice": 259
        }
      ],
      "lastFetchedAt": 1781692205000
    }
  }
}

`getMineById`

Source: backend/endpoints/provider-orders/get-mine-by-id

Returns a single provider order belonging to the authenticated patient. The response is enriched with organization, lab order, lab result file metadata, and Shadowfax fulfillment details for patient-facing mobile/web flows. Shadowfax details use the same GET /api/v2/orders/{sfx_order_id}/status/ API and also populate deliveryTracking.

Input Fields

Field	Type	Required
`id`	`string`	Yes

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_required>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "getMineById",
  "data": {
    "id": "provider_order_123"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`listByOrganization`

Source: backend/endpoints/provider-orders/list-by-organization

Lists provider orders for an organization. Supports source/status filters, search, sorting, pagination, and YYYY-MM-DD date filtering. Date filters use valid scheduledDate values first and fall back to order createdAt.

Input Fields

Field	Type	Required
`organizationId`	`string`	Yes
`sourceType`	`string`	No
`status`	`string`	No
`search`	`string`	No
`sortBy`	`string`	No
`sortOrder`	`string`	No
`startDate`	`string (YYYY-MM-DD)`	No
`endDate`	`string (YYYY-MM-DD)`	No
`page`	`int`	No
`pageSize`	`int`	No

Response Notes

The response includes statusOptions for building the status filter UI.
For sourceType: "lab_order", statusOptions is ["pending", "confirmed", "collected", "processing", "completed", "cancelled"].
For sourceType: "prescription", statusOptions is ["pending", "confirmed", "packing", "dispatched", "out_for_delivery", "delivered", "cancelled"].
If sourceType is omitted or unknown, the response returns the combined provider-order status list.

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "listByOrganization",
  "data": {
    "organizationId": "org_123",
    "sourceType": "lab_order",
    "startDate": "2026-05-22",
    "endDate": "2026-05-22",
    "page": 1,
    "pageSize": 100
  }
}'

Example Response

{ "status": "ok", "data": {} }

`getAdminOrderStats`

Source: backend/endpoints/provider-orders/get-admin-order-stats

Returns provider-order dashboard counts. Use this endpoint for the lab order summary cards instead of deriving stats from one paginated list page.

Input Fields

Field	Type	Required
`organizationId`	`string`	Yes
`sourceType`	`string`	No
`startDate`	`string (YYYY-MM-DD)`	No
`endDate`	`string (YYYY-MM-DD)`	No

Output Fields

Field	Type
`totalOrders`	`int`
`pendingOrders`	`int`
`paidOrders`	`int`
`totalRevenue`	`float64`
`medicationOrders`	`int`
`labOrders`	`int`
`pendingCollection`	`int`
`successfullyCollected`	`int`
`currentlyProcessing`	`int`
`resultsCompleted`	`int`

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "getAdminOrderStats",
  "data": {
    "organizationId": "org_123",
    "sourceType": "lab_order",
    "startDate": "2026-05-22",
    "endDate": "2026-05-22"
  }
}'

Example Response

{
  "status": "ok",
  "data": {
    "pendingCollection": 1,
    "successfullyCollected": 5,
    "currentlyProcessing": 2,
    "resultsCompleted": 1
  }
}

`listMine`

Source: backend/endpoints/provider-orders/list-mine

Lists provider orders belonging to the authenticated patient. This endpoint is intended for patient apps and returns provider-order rows enriched with provider code/external order metadata.

Input Fields

Field	Type	Required
`page`	`int`	No
`pageSize`	`int`	No

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_required>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "listMine",
  "data": {
    "page": 1,
    "pageSize": 20
  }
}'

Example Response

{ "status": "ok", "data": {} }

`update`

Source: backend/endpoints/provider-orders/update

Updates an Aivida provider order. If the updated order is already synced to Shadowfax (fulfillmentProvider: "SHADOWFAX" and externalOrderId is present), the same providerOrders.update API also syncs the edit to Shadowfax. No separate Aivida edit endpoint is needed.

The active Super Admin Shadowfax flow decides which Shadowfax edit API is called. on_demand is the default.

Shadowfax On-Demand Edit Mapping

PUT /api/v2/orders/{sfx_order_id}/edit/

Shadowfax payload:

{
  "order_details": {
    "order_value": 248,
    "paid": "true",
    "client_order_id": "SHX9004400",
    "rain_flag": false,
    "delivery_instruction": {
      "drop_instruction_text": "Don't call me. Please come to the first floor and ring the doorbell.",
      "take_drop_off_picture": true,
      "drop_off_picture_mandatory": true
    },
    "client_surge": 0
  },
  "client_code": "merchant001",
  "pickup_details": {
    "city": "Delhi",
    "contact_number": "6749883397",
    "name": "Store name",
    "longitude": 77.0563207,
    "address": "Store address in plain text",
    "latitude": 28.5833332
  },
  "order_items": [
    {
      "name": "Item name",
      "price": 259,
      "quantity": 3,
      "id": "29656019"
    }
  ],
  "drop_details": {
    "name": "Customer name",
    "longitude": 77.037531,
    "address": "Customer address in plain text",
    "latitude": 28.588891,
    "contact_number": "9987654321",
    "city": "Delhi"
  }
}

Shadowfax Dedicated Edit Mapping

PUT /api/v1/stores/edit-order/

Shadowfax payload:

{
  "store_code": "STORE_CODE",
  "sfx_order_id": 9228119,
  "COID": "150340000010725",
  "amount": 420,
  "rain_flag": false,
  "paid": false,
  "product_details": [
    {
      "id": 12095247,
      "weight": 0.5,
      "quantity": 1,
      "name": "Rajma Jamu",
      "price": 130
    },
    {
      "weight": 0.5,
      "quantity": 4,
      "name": "Mangat Ram Pulses Chana Dal",
      "price": 68.5,
      "id": 12095248
    }
  ]
}

Dedicated edit requires the organization to have shadowfax_store_code configured. If Shadowfax rejects the edit, providerOrders.update returns the provider error so the caller knows the external order was not updated.

Input Fields

Field	Type	Required
`id`	`string`	Yes
`organizationId`	`string`	Yes
`patientProfileId`	`*string`	No
`sourceType`	`*string`	No
`prescriptionId`	`*string`	No
`labOrderId`	`*string`	No
`appointmentId`	`*string`	No
`consultationId`	`*string`	No
`items`	`*[]models.ProviderOrderItem`	No
`subtotal`	`*float64`	No
`status`	`*string`	No
`deliveryAddress`	`*models.ProviderOrderDeliveryAddress`	No
`confirmedAt`	`*int64`	No
`packingAt`	`*int64`	No
`dispatchedAt`	`*int64`	No
`outForDeliveryAt`	`*int64`	No
`deliveredAt`	`*int64`	No
`patientNotes`	`*string`	No
`providerNotes`	`*string`	No
`razorpayOrderId`	`*string`	No
`razorpayPaymentId`	`*string`	No
`razorpaySignature`	`*string`	No
`paymentStatus`	`*string`	No
`amountPaid`	`*float64`	No
`paidAt`	`*int64`	No
`paymentMethod`	`*string`	No
`checkoutSessionId`	`*string`	No
`createdAt`	`*int64`	No
`updatedAt`	`*int64`	No

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "providerOrders",
  "apiName": "update",
  "data": {
    "id": "id_123",
    "organizationId": "org_123"
  }
}'

Example Response

{ "status": "ok", "data": {} }

Lab Provider