E-shop Types

Type definitions for the E-shop module.

Product

interface Product {
  id: string;
  key: string;
  store_id: string;
  slug: Record<string, string>;
  blocks: Block[];
  taxonomies: TaxonomyEntry[];
  variants: ProductVariant[];
  contact_list_ids: string[];
  status: ProductStatus; // 'active' | 'draft' | 'archived'
  created_at: number;
  updated_at: number;
}

type ProductStatus = 'active' | 'draft' | 'archived';

Order

interface Order {
  id: string;
  number: string;
  store_id: string;
  source_cart_id: string;
  contact_id: string;
  status: OrderStatus;
  payment_status: OrderPaymentSummaryStatus;
  fulfillment_status: OrderFulfillmentStatus;
  verified: boolean;
  items: OrderItem[];
  payment: OrderPayment;
  shipping_lines: ShippingLine[];
  fulfillment_orders: FulfillmentOrder[];
  shipping_address?: Address;
  billing_address?: Address;
  forms: FormEntry[];
  shipments: Shipment[];
  digital_access_grants: DigitalAccessGrant[];
  history: HistoryEntry[];
  contact_list_id?: string;
  fired_reminders: number[];
  created_at: number;
  updated_at: number;
}

type OrderStatus =
  | 'pending'
  | 'partially_confirmed'
  | 'confirmed'
  | 'partially_cancelled'
  | 'cancelled'
  | 'completed';

type OrderPaymentSummaryStatus =
  | 'unpaid'
  | 'pending'
  | 'authorized'
  | 'partially_paid'
  | 'paid'
  | 'partially_refunded'
  | 'refunded'
  | 'failed'
  | 'voided'
  | 'expired';

type OrderFulfillmentStatus =
  | 'unfulfilled'
  | 'scheduled'
  | 'on_hold'
  | 'in_progress'
  | 'partially_fulfilled'
  | 'fulfilled'
  | 'incomplete'
  | 'not_required';

interface ShippingLine {
  id: string;
  shipping_method_id?: string | null;
  title: string;
  code?: string | null;
  source: string;
  carrier_identifier?: string | null;
  money: LineMoneySnapshot;
}

interface FulfillmentOrder {
  id: string;
  order_id: string;
  assigned_location_id: string;
  status: 'open' | 'in_progress' | 'closed' | 'incomplete' | 'on_hold' | 'scheduled' | 'cancelled';
  lines: FulfillmentOrderLine[];
}

interface FulfillmentOrderLine {
  id: string;
  order_item_id: string;
  quantity: number;
  fulfilled_quantity: number;
}

Shipping lines are buyer-facing pricing records. Fulfillment orders are the internal work queue for physical items. Shipments are carrier/label/tracking records that satisfy fulfillment order lines.

Order Item

type OrderItem = ProductLineItem | ServiceLineItem;

type OrderItemStatus =
  | { status: 'pending'; expires_at: number }
  | { status: 'confirmed' }
  | { status: 'cancelled'; reason: OrderCancellationReason };

type OrderItemFulfillmentStatus =
  | 'unfulfilled'
  | 'partially_fulfilled'
  | 'fulfilled'
  | 'not_required';

type BookingOrderItemStatus =
  | 'scheduled'
  | 'completed'
  | 'no_show'
  | 'cancelled';

interface ProductLineItem {
  type: 'product';
  id: string;
  product_id: string;
  variant_id: string;
  quantity: number;
  cancelled_quantity: number;
  fulfilled_quantity: number;
  returned_quantity: number;
  refunded_quantity: number;
  snapshot: ProductLineItemSnapshot;
  status: OrderItemStatus;
  fulfillment_status: OrderItemFulfillmentStatus;
  money: LineMoneySnapshot;
}

interface ServiceLineItem {
  type: 'service';
  id: string;
  service_id: string;
  provider_id: string;
  from: number;
  to: number;
  quantity: number;
  cancelled_quantity: number;
  fulfilled_quantity: number;
  refunded_quantity: number;
  forms: FormEntry[];
  snapshot: ServiceLineItemSnapshot;
  status: OrderItemStatus;
  booking_status: BookingOrderItemStatus;
  fulfillment_status: OrderItemFulfillmentStatus;
  money: LineMoneySnapshot;
}

Service items are scheduled bookings inside the normal order. They are not a separate order type and they do not use a separate checkout model.

Digital Access Grant

type DigitalAccessGrantStatus =
  | 'pending'
  | 'active'
  | 'exhausted'
  | 'revoked'
  | 'expired';

interface DigitalAccessGrant {
  id: string;
  order_id: string;
  order_item_id: string;
  product_id: string;
  variant_id: string;
  contact_id: string;
  asset_id: string;
  asset_name_snapshot: string;
  type: 'file' | 'external_link';
  access_url?: string | null;
  storage_ref?: string | null;
  status: DigitalAccessGrantStatus;
  download_limit?: number | null;
  download_count: number;
  expires_at?: number | null;
  granted_at?: number | null;
  revoked_at?: number | null;
}

Payment

interface OrderPayment {
  status: OrderPaymentStatus;
  currency: string;
  market: string;
  subtotal: number;
  shipping: number;
  discount: number;
  total: number;
  paid: number;
  authorized_amount: number;
  captured_amount: number;
  refunded_amount: number;
  voided_amount: number;
  capture_method: 'automatic' | 'manual';
  tax?: {
    amount: number;
    mode_snapshot?: string;
    rate_bps: number;
    lines: Array<{
      rate_bps: number;
      amount: number;
      label?: string;
      scope?: string;
    }>;
  };
  promo_code?: {
    id: string;
    code: string;
    type: string;
    value: number;
  };
  provider?: {
    type: 'stripe';
    stripe_customer_id: string;
    payment_intent_id?: string | null;
  };
  refunds: OrderPaymentRefund[];
  transactions: PaymentTransaction[];
  provider_payment_id?: string | null;
  provider_customer_id?: string | null;
  provider_payment_method_id?: string | null;
  provider_status?: string | null;
  next_action?: string | null;
  failure_code?: string | null;
  failure_message?: string | null;
  idempotency_key?: string | null;
  zone_id?: string;
  payment_method_key?: string;
  shipping_method_id?: string;
  method_type: PaymentMethodType;
}

type OrderPaymentStatus =
  | { status: 'pending'; at: number }
  | { status: 'requires_action'; at: number; reason?: string | null }
  | { status: 'processing'; at: number }
  | { status: 'authorized'; at: number; amount: number }
  | { status: 'partially_captured'; at: number; amount: number }
  | { status: 'captured'; at: number; amount: number }
  | { status: 'partially_refunded'; at: number; amount: number }
  | { status: 'refunded'; at: number; amount: number }
  | { status: 'voided'; at: number; amount: number }
  | { status: 'cancelled'; at: number; reason?: string | null }
  | { status: 'expired'; at: number }
  | { status: 'failed'; at: number; reason?: string | null };

enum PaymentMethodType {
  Cash = 'cash',
  CreditCard = 'credit_card',
}

interface OrderPaymentRefund {
  id: string;
  type: string;
  total: number;
  tax_amount: number;
  shipping_amount?: number | null;
  provider_refund_id?: string;
  status: string;
  reason?: string | null;
  lines: RefundLine[];
  transaction_ids: string[];
  created_at: number;
}

Quote

interface Quote {
  market: string;
  zone: Zone | null;
  subtotal: number;
  shipping: number;
  discount: number;
  tax: number;
  total: number;
  shipping_method: ShippingMethod | null;
  payment_method: PaymentMethod | null;
  payment_methods: PaymentMethod[];
  promo_code: PromoCodeValidation | null;
  payment: OrderPayment;
  charge_amount: number;
  id?: string;
  expires_at?: number;
}

interface PromoCodeValidation {
  promo_code_id: string;
  code: string;
  discounts: any[];
  conditions: any[];
}

Checkout Response

interface OrderCheckoutResult {
  order_id: string;
  number: string;
  payment_action: { type: 'none' } | { type: 'handle_next_action'; client_secret: string };
  payment: OrderPayment;
}

Promo Code

interface PromoCode {
  id: string;
  store_id: string;
  code: string;
  discounts: Discount[];
  conditions: Condition[];
  status: PromoCodeStatus; // 'active' | 'draft' | 'archived'
  created_at: number;
  updated_at: number;
}

type PromoCodeStatus = 'active' | 'draft' | 'archived';

interface Discount {
  type: 'items_percentage' | 'items_fixed' | 'shipping_percentage';
  market_id: string;
  bps?: number;
  amount?: number;
}

interface Condition {
  type:
    | 'products'
    | 'services'
    | 'min_order_amount'
    | 'date_range'
    | 'max_uses'
    | 'max_uses_per_user';
  value: string[] | number | { start?: number; end?: number };
}

Cart Item (Client-Side)

interface EshopCartItem {
  id: string;
  product_id: string;
  variant_id: string;
  product_name: string;
  product_slug: string;
  variant_attributes: Record<string, any>;
  price: Price;
  quantity: number;
  added_at: number;
}

Product Category

interface ProductCategory {
  slug: string;
  name: string;
  description?: string;
  image?: string;
  parent_slug?: string;
  product_count: number;
}

Inventory Event

interface InventoryEvent {
  product_id: string;
  type: 'INCREMENT' | 'DECREMENT' | 'SET';
  quantity: number;
  reason?: string;
  order_id?: string;
  timestamp: number;
}

Filter & Sort Options

interface ProductFilters {
  status?: ProductStatus; // 'active' | 'draft' | 'archived'
  category?: string;
  min_price?: number;
  max_price?: number;
  in_stock?: boolean;
  search?: string;
}

interface ProductSort {
  field: 'created_at' | 'name' | 'price' | 'inventory';
  order: 'asc' | 'desc';
}