@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

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

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