@deliverart/sdk-js-order

Order management package for the DeliverArt JavaScript SDK.

Installation

npm install @deliverart/sdk-js-order @deliverart/sdk-js-core
# or
pnpm add @deliverart/sdk-js-order @deliverart/sdk-js-core

Exported Types

Core Types

type OrderType = 'delivery' | 'collection' | 'kitchen'
type OrderStatus = 'pending' | 'confirmed' | 'rejected'
type OrderPreparationStatus = 'to_prepare' | 'in_preparation' | 'done'
type OrderSource = 'application' | 'ecommerce' | 'partner'
type OrderPlanningMode = 'PLANNED' | 'FORCED'

Models

• Order
• OrderDetails
• DeliveryOrder
• CollectionOrder
• TakeAwayOrder (deprecated alias)
• KitchenOrder
• DeliveryOrderDetails
• CollectionOrderDetails
• TakeAwayOrderDetails (deprecated alias)
• KitchenOrderDetails
• WritableOrder
• WritableUpdateOrder
• OrderMenuItem
• OrderMenuItemDetails
• OrderMenuItemModifier
• OrderMenuItemModifierDetails
• Bundle
• BundleDetails
• WritableBundle
• FeeSimulation
• OrderRescheduleWindow
• OrderRescheduleOption
• OrderRescheduleReferenceBundle
• OrderRating
• WritableOrderRating
• OrderIntegrationExport
• OrderIntegrationExportDetails
• OrderIntegrationExportAttempt

Typed Inputs and Outputs

Order and OrderDetails are discriminated by type.

• delivery orders expose delivery-specific fields like address, requestedDeliveryTime, finalDeliveryTime, deliveryStartedAt, deliveredAt
• collection orders expose collection-specific fields like requestedCollectionTime, finalCollectionTime, collectedAt
• kitchen orders exclude both delivery and collection scheduling fields
• all order read models also expose scheduling metadata such as scheduledWindowStart, scheduledWindowEnd, schedulingVersion and planningMode
• delivery read models additionally expose estimatedRouteDurationSeconds, estimatedRouteDistanceMeters and stopSequence

CreateOrderInput and CalculateOrderFeesInput are also discriminated by type.

• delivery accepts fields such as address, customerAddress, locationData, referenceBundle, deliveryTime
• collection accepts collectionTime
• the legacy alias take_away is still accepted on write for backward compatibility
• kitchen does not accept delivery or collection scheduling fields
• all writable order inputs also accept forceScheduling?: boolean for internal operator-only retries that bypass slot/capacity validation

UpdateOrderInput keeps common editable fields and enforces mutually exclusive delivery / collection scheduling fields.

Order Requests

CreateOrder

import { CreateOrder } from '@deliverart/sdk-js-order'

const order = await sdk.call(
  new CreateOrder({
    type: 'delivery',
    source: 'application',
    pointOfSale: '/point_of_sales/123e4567-e89b-12d3-a456-426614174000',
    customer: '/customers/123e4567-e89b-12d3-a456-426614174001',
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phoneNumber: '+39123456789',
    },
    address: {
      line1: 'Via Roma 1',
      city: 'Milano',
      postalCode: '20100',
      country: 'IT',
    },
    deliveryTime: '2026-03-22T19:30:00+01:00',
    items: [
      {
        menuItem: '/menu_items/123e4567-e89b-12d3-a456-426614174002',
        salesMode: null,
        variant: null,
        quantity: 2,
        notes: 'No onions',
        removals: [],
        modifiers: [],
      },
    ],
  }),
)

Response: OrderDetails

Completed ecommerce orders expose rating, which is null until the owning customer submits a rating. A rating contains an order score from 1 to 5, an optional delivery score for delivery orders, and an optional comment.

Order ratings

import { CreateOrderRating, UpdateOrderRating } from '@deliverart/sdk-js-order'

const rating = await sdk.call(
  new CreateOrderRating({
    order: '/orders/123e4567-e89b-12d3-a456-426614174003',
    orderScore: 5,
    deliveryScore: 4,
    comment: 'Puntuale e tutto caldo.',
  }),
)

await sdk.call(
  new UpdateOrderRating(rating.id, {
    deliveryScore: 5,
  }),
)

Only the ecommerce customer who owns the completed order can create or update its rating. deliveryScore is accepted only for delivery orders.

Useful response fields after create/update

• scheduledWindowStart
• scheduledWindowEnd
• planningMode
• schedulingVersion
• for delivery: estimatedRouteDurationSeconds, estimatedRouteDistanceMeters, stopSequence

planningMode can be:

• PLANNED
• FORCED

CalculateOrderFees

import { CalculateOrderFees } from '@deliverart/sdk-js-order'

const fees = await sdk.call(
  new CalculateOrderFees({
    type: 'collection',
    source: 'application',
    pointOfSale: '/point_of_sales/123e4567-e89b-12d3-a456-426614174000',
    collectionTime: '2026-03-22T20:00:00+01:00',
    items: [
      {
        menuItem: '/menu_items/123e4567-e89b-12d3-a456-426614174002',
        salesMode: null,
        variant: null,
        quantity: 1,
        notes: null,
        removals: [],
        modifiers: [],
      },
    ],
  }),
)

Response: FeeSimulation

GetOrders

import { GetOrders } from '@deliverart/sdk-js-order'

const orders = await sdk.call(
  new GetOrders({
    query: {
      type: ['delivery', 'collection'],
      status: ['pending', 'confirmed'],
      preparationStatus: 'to_prepare',
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Main query params

• type?: OrderType | OrderType[]
• source?: OrderSource | OrderSource[]
• status?: OrderStatus | OrderStatus[]
• preparationStatus?: OrderPreparationStatus | OrderPreparationStatus[]
• paymentMethod?: PaymentMethod | PaymentMethod[]
• paymentStatus?: PaymentStatus | PaymentStatus[]
• partner?: OrderPartner | OrderPartner[]
• partnerIdentifier?: string | string[]
• isRead?: boolean
• exists[acceptedAt]?: boolean
• exists[preparationEndedAt]?: boolean
• exists[collectedAt]?: boolean
• exists[deliveredAt]?: boolean
• page?: number

Response: Paginated<Order>

GetOrderDetails

import { GetOrderDetails } from '@deliverart/sdk-js-order'

const order = await sdk.call(new GetOrderDetails('123e4567-e89b-12d3-a456-426614174003'))

Response: OrderDetails

Every order read model exposes originIntegration, the exact Integration IRI that created an inbound order when one is known. This is not a generic partner or service name: it identifies the one integration instance excluded from the order's outbound fan-out.

Per-integration destination delivery

Canonical order persistence and delivery to CassaInCloud, Tilby, or future destinations are separate lifecycles. After confirmation, the API creates one OrderIntegrationExport for every eligible concrete destination integration. Two integrations using the same service remain two independent rows.

import {
  GetOrderIntegrationExportDetails,
  GetOrderIntegrationExports,
  RetryOrderIntegrationExport,
} from '@deliverart/sdk-js-order'

const exports = await sdk.call(
  new GetOrderIntegrationExports('123e4567-e89b-12d3-a456-426614174003'),
)

const details = await sdk.call(
  new GetOrderIntegrationExportDetails(exports[0].id),
)

if (details.status === 'failed' || details.status === 'manual_action') {
  await sdk.call(new RetryOrderIntegrationExport(details.id))
}

GetOrderIntegrationExports returns an unpaginated collection scoped to one order. The detail request includes append-only attemptHistory. RetryOrderIntegrationExport returns 202 Accepted and starts a new generation; it never creates a second canonical order.

Lifecycle statuses:

• pending
• processing
• retry_scheduled
• outcome_unknown
• succeeded
• failed
• manual_action
• skipped
• cancelled

Phases are eligibility, catalog_preparation, payload_validation, sending, reconciling, and completed. Treat outcome_unknown as reconciliation work, not as permission to send blindly again. technicalError is optional because the API exposes it only to administrators; public clients must rely on the typed public error fields.

GetPointOfSaleOrders

import { GetPointOfSaleOrders } from '@deliverart/sdk-js-order'

const orders = await sdk.call(
  new GetPointOfSaleOrders('123e4567-e89b-12d3-a456-426614174000', {
    query: {
      status: 'pending',
      page: 1,
    },
  }),
)

Response: Paginated<Order>

GetCustomerOrders

import { GetCustomerOrders } from '@deliverart/sdk-js-order'

const orders = await sdk.call(
  new GetCustomerOrders('123e4567-e89b-12d3-a456-426614174001', {
    query: {
      status: 'confirmed',
      page: 1,
    },
  }),
)

Response: Paginated<Order>

UpdateOrder

import { UpdateOrder } from '@deliverart/sdk-js-order'

const updated = await sdk.call(
  new UpdateOrder('123e4567-e89b-12d3-a456-426614174003', {
    notes: 'Updated notes',
    deliveryTime: '2026-03-22T20:15:00+01:00',
  }),
)

Response: OrderDetails

GetOrderRescheduleOptions

import { GetOrderRescheduleOptions } from '@deliverart/sdk-js-order'

const windows = await sdk.call(
  new GetOrderRescheduleOptions('123e4567-e89b-12d3-a456-426614174003', {
    query: {
      date: '2026-03-22',
      includeInvalid: true,
    },
  }),
)

Query params

• date?: string
• searchFrom?: string
• includeInvalid?: boolean

Response: OrderRescheduleWindow[]

Each option contains:

• scheduledAt
• rangeStart
• rangeEnd
• status
• available
• invalidReason
• referenceBundles

status can be:

• keep_current_bundle
• create_new_bundle
• move_to_reference_bundle
• unavailable

invalidReason can be:

• store_closed
• no_capacity
• outside_lead_time
• journey_outside_window

Lifecycle and Payment Requests

import {
  AdvanceOrderPreparationStatus,
  ConfirmOrder,
  MarkOrderAsCollected,
  MarkOrderAsRead,
  PayOrder,
  RejectOrder,
} from '@deliverart/sdk-js-order'

await sdk.call(new ConfirmOrder('123e4567-e89b-12d3-a456-426614174003'))
await sdk.call(new AdvanceOrderPreparationStatus('123e4567-e89b-12d3-a456-426614174003'))
await sdk.call(new MarkOrderAsRead('123e4567-e89b-12d3-a456-426614174003'))
await sdk.call(new MarkOrderAsCollected('123e4567-e89b-12d3-a456-426614174003'))
await sdk.call(new RejectOrder('123e4567-e89b-12d3-a456-426614174003'))
await sdk.call(new PayOrder('123e4567-e89b-12d3-a456-426614174003', 'cash'))
await sdk.call(
  new PayOrder('123e4567-e89b-12d3-a456-426614174003', 'stripe', {
    successUrl:
      'https://ecommerce.deliverart.it/restaurant/orders/123e4567-e89b-12d3-a456-426614174003?payment=success',
    cancelUrl:
      'https://ecommerce.deliverart.it/restaurant/orders/123e4567-e89b-12d3-a456-426614174003?payment=cancel',
  }),
)

Available requests

• ConfirmOrder
• RejectOrder
• AdvanceOrderPreparationStatus
• MarkOrderAsRead
• MarkOrderAsCollected
• PayOrder
• DeleteOrder
• GetOrderRescheduleOptions
• GenerateOrderBundle

Order Menu Items

GetOrderMenuItems

import { GetOrderMenuItems } from '@deliverart/sdk-js-order'

const items = await sdk.call(
  new GetOrderMenuItems({
    query: {
      type: ['ITEM', 'BUNDLE'],
      action: 'add',
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Response: Paginated<OrderMenuItem>

GetOrderMenuItemDetails

import { GetOrderMenuItemDetails } from '@deliverart/sdk-js-order'

const item = await sdk.call(new GetOrderMenuItemDetails('123e4567-e89b-12d3-a456-426614174004'))

Response: OrderMenuItemDetails

GetOrderMenuItemModifiers

import { GetOrderMenuItemModifiers } from '@deliverart/sdk-js-order'

const modifiers = await sdk.call(
  new GetOrderMenuItemModifiers({
    query: {
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Response: Paginated<OrderMenuItemModifier>

GetOrderMenuItemModifierDetails

import { GetOrderMenuItemModifierDetails } from '@deliverart/sdk-js-order'

const modifier = await sdk.call(
  new GetOrderMenuItemModifierDetails('123e4567-e89b-12d3-a456-426614174005'),
)

Response: OrderMenuItemModifierDetails

Bundles

Bundle and BundleDetails are discriminated by type.

• REGULAR
• FORCED

Bundle read models also expose:

• capacityUsed
• plannedStops
• routeDurationSeconds
• routeDistanceMeters
• slackSeconds
• plannerVersion

CreateBundle

import { CreateBundle } from '@deliverart/sdk-js-order'

const bundle = await sdk.call(
  new CreateBundle({
    pointOfSale: '/point_of_sales/123e4567-e89b-12d3-a456-426614174000',
    deliverable: true,
    ready: false,
  }),
)

Response: BundleDetails

GenerateOrderBundle

import { GenerateOrderBundle } from '@deliverart/sdk-js-order'

const order = await sdk.call(new GenerateOrderBundle('123e4567-e89b-12d3-a456-426614174003'))

Response: OrderDetails

Use this only for orders that currently have no bundle.

GetBundles

import { GetBundles } from '@deliverart/sdk-js-order'

const bundles = await sdk.call(
  new GetBundles({
    query: {
      status: ['pending', 'busy'],
      type: 'REGULAR',
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Response: Paginated<Bundle>

GetBundleDetails

import { GetBundleDetails } from '@deliverart/sdk-js-order'

const bundle = await sdk.call(new GetBundleDetails('123e4567-e89b-12d3-a456-426614174006'))

Response: BundleDetails

GetBundlesFromPointOfSale

import { GetBundlesFromPointOfSale } from '@deliverart/sdk-js-order'

const bundles = await sdk.call(
  new GetBundlesFromPointOfSale('123e4567-e89b-12d3-a456-426614174000', {
    query: {
      ready: false,
      page: 1,
    },
  }),
)

Response: Paginated<Bundle>

UpdateBundle

import { UpdateBundle } from '@deliverart/sdk-js-order'

const updated = await sdk.call(
  new UpdateBundle('123e4567-e89b-12d3-a456-426614174006', {
    ready: true,
  }),
)

Response: BundleDetails

Available requests

• CreateBundle
• GetBundles
• GetBundlesFromPointOfSale
• GetBundleDetails
• UpdateBundle
• DeleteBundle

License

MIT