Skip to content

OrderState ​

Type: schema

Description ​

An order as its events carry it: its status, totals, items, addresses and payments, the customer's contact (customer_email, customer_phone), who cancelled the order, and the KYC and ERP ledger details recorded when the merchant approved it.

TypeScript Definition ​

typescript
OrderState: {{
            /** @description Unique, human-readable order identifier used across all order endpoints. */
            order_number: string;
            /** Format: date-time */
            order_date: string;
            /**
             * @description Current fulfillment status of the order. Progresses from `confirmed` through shipping stages to `complete`; a collect-in-store order with nothing to ship is `complete` as soon as it is paid, unless it was already accepted on the customer's credit line (it then stays `confirmed`). `pending` while it awaits payment, and `payment_failed` once every payment attempt failed (a payment retry reopens it). An order with one shipment can also take that shipment's `schedule_requested`, `processing`, `sent_to_store`, `ready_to_collect` or `lost`.
             * @enum {string}
             */
            status: "draft" | "awaiting_approval" | "confirmed" | "partially_scheduled" | "awaiting_shipment" | "shipped" | "partially_shipped" | "undelivered" | "partially_undelivered" | "return_to_origin" | "partially_return_to_origin" | "complete" | "partially_delivered" | "cancelled" | "pending" | "schedule_requested" | "payment_failed" | "sent_to_store" | "ready_to_collect" | "processing" | "lost";
            /**
             * @description The order's payment status. `debit_scheduled` and `collection_due`: the order is on the customer's credit line, to be debited from their bank account by NACH mandate, or collected later. `refund_initiated` and `refunded`: refunds covering what was paid are on their way, or done. `manual_review`: the payment is being reviewed.
             * @enum {string}
             */
            payment_status: "pending" | "success" | "failed" | "partially_paid" | "refund_initiated" | "refunded" | "debit_scheduled" | "collection_due" | "manual_review";
            payment_success_date: string | null;
            customer_note: string | null;
            is_promotion_applied: boolean;
            /** Format: double */
            promotion_discount_amount: number;
            /** Format: double */
            promotion_discount_percent: number | null;
            is_coupon_applied: boolean;
            coupon_code: string | null;
            /** Format: double */
            coupon_discount_amount: number;
            /** Format: double */
            coupon_discount_percent: number | null;
            /** @description Information about the promotional offers that have been applied to the cart. */
            applied_promotions: components["schemas"]["AppliedPromotion"][];
            /** @description This key provides details about the savings in cart after coupon have been applied to the cart. */
            applied_coupons: components["schemas"]["AppliedCoupon"][];
            /**
             * Format: float
             * @description Total savings from auto-applied promotions.
             */
            promotion_savings: number;
            /**
             * Format: float
             * @description Total savings from the applied coupon code.
             */
            coupon_savings: number;
            /**
             * Format: float
             * @description Total savings from loyalty points, credit balance, and other non-promotion/coupon discounts.
             */
            other_savings: number;
            /**
             * Format: float
             * @description Combined savings across promotions, coupons, and other discounts.
             */
            total_savings: number;
            on_subscription: boolean;
            /** Format: double */
            subtotal: number;
            /** Format: double */
            subtotal_including_tax: number;
            /** Format: double */
            shipping_estimated_cost: number;
            /** Format: double */
            shipping_discount_amount: number;
            /** Format: double */
            shipping_amount: number;
            /** Format: double */
            shipping_tax_rate: number;
            /** Format: double */
            shipping_tax_amount: number;
            /** Format: double */
            shipping_amount_including_tax: number;
            estimated_delivery_days: number | null;
            /** Format: double */
            handling_charge_excluding_tax: number;
            /** Format: double */
            handling_charge_tax_amount: number;
            /** Format: double */
            handling_charge_including_tax: number;
            /** Format: double */
            total_tax: number;
            /** Format: double */
            grand_total: number;
            loyalty_points_earned: number;
            loyalty_points_redeemed: number;
            credit_balance_used: number;
            /** Format: double */
            to_be_paid: number;
            order_items_count: number;
            order_items: components["schemas"]["OrderStateItem"][];
            billing_address: components["schemas"]["OrderAddress"];
            shipping_address: components["schemas"]["OrderAddress"];
            currency: {
                name?: string;
                code?: string;
                symbol?: string;
            };
            /** @description Additional metadata associated with the order: its point-of-sale details and its custom metadata (under `custom_metadata`). `null` when the order has none. */
            metadata: {
                /** @description The point-of-sale user who placed the order; `null` when not placed at a point of sale. */
                pos_user_id: string | null;
                /** @description The point-of-sale device the order was placed on; `null` when not placed at a point of sale. */
                pos_device_id: string | null;
                /** @description The store location the order was placed at; `null` when not set. */
                origin_location_id: string | null;
                /** @description The custom metadata given for the order. */
                custom_metadata: Record<string, never> | null;
            } | null;
            /** @description Whether the order is eligible for cancellation. Only show the cancel action in your UI when this is `true`. */
            is_cancellation_allowed: boolean;
            /** @description Breakdown of the refund the customer would receive upon cancellation. */
            cancellation_refund_details: {
                /** @description loyalty point redeemed will be rollbacked and credited to user account. */
                loyalty_point?: number;
                /** @description amount that will be refunded to customer. */
                refundable_amount?: number;
                /** @description amount deducted from paid amount. */
                cancellation_charges?: number;
                /** @description reason for cancellation charges. */
                cancellation_charges_reason?: string;
                /**
                 * @description payment mode for refund.
                 * @enum {string}
                 */
                payment_mode?: "original-payment-mode" | "bank-transfer" | "nach-mandate";
            };
            feedback: string | null;
            /** @description ULID of the cart this order was created from. `null` if unavailable. */
            cart_id: string | null;
            /** @description ID of the applied coupon. `null` when no coupon is applied. */
            coupon_id: string | null;
            /** @description Reason the order was cancelled. `null` when not cancelled. */
            cancellation_reason: string | null;
            /** @description Order-level shipping provider ID. `null` until resolved. */
            shipping_provider_id: string | null;
            /** @description Order-level courier company ID. `null` until resolved. */
            courier_company_id: string | null;
            /** @description Order-level shipping provider name. Always `null`: the provider is resolved per shipment. */
            shipping_provider_name: string | null;
            /** @description Order-level courier company name. Always `null`: the courier is resolved per shipment. */
            courier_company_name: string | null;
            /** @description Fulfillment type for the order (e.g. `delivery`, `collect-in-store`). */
            fulfillment_type: string;
            /**
             * Format: double
             * @description Total tax amount for the order items.
             */
            items_tax_amount: number;
            /** @description Order amount eligible for loyalty-point earning. */
            loyalty_point_eligible_amount: number;
            /** @description The sales channel the order was placed through: its `id` and `type` (e.g. `web`, `app`, `pos`), each `null` when not recorded. */
            sales_channel: {
                id: string | null;
                type: string | null;
            };
            /** @description The order's refunds, then its payments. A seller's copy of a marketplace order has one entry standing for the marketplace order's payment. */
            payments: (components["schemas"]["OrderPaymentEvent"] | components["schemas"]["MarketplaceOrderPayment"])[];
            /** @description The customer's email: the order's contact email, else its billing or shipping address's. */
            customer_email: string | null;
            /** @description The customer's phone number: the order's contact phone, else its billing or shipping address's. */
            customer_phone: string | null;
            /** @description Who cancelled the order: `customer`, `system` (cancelled automatically, e.g. when left unpaid) or `admin:` followed by the admin's email. `null` when not cancelled, or cancelled through its shipments. */
            cancelled_by: string | null;
            /** @description The customer's KYC documents and customer group, recorded when the merchant approved the order. `null` until then, or when none were recorded. */
            kyc_details: {
                documents?: {
                    /** @enum {string} */
                    document_type?: "gst" | "pan" | "drug_license" | "drug_license2";
                    document_number?: string | null;
                    status?: string | null;
                    is_verified?: boolean | null;
                    is_mandatory?: boolean | null;
                    is_attachment_required?: boolean | null;
                }[];
                /** @description The customer's group; empty when they have none. */
                customer_group?: string;
            } | null;
            /** @description The customer's ledger in the store's ERP that the order is booked to, recorded when the merchant approved the order. `null` when none is kept for it. */
            erp_ledger: {
                service_provider_id?: string | null;
                service_provider_slug?: string | null;
                service_provider_name?: string | null;
                /** @description The ledger's id in the ERP. */
                external_ledger_id?: string | null;
            } | null;
        };
        /**
         * OrderStateItem
         * @description An item of an order as its events carry it.
         */
}

Component References ​

ReferenceResolves To
components["schemas"]["AppliedPromotion"]AppliedPromotion
components["schemas"]["AppliedCoupon"]AppliedCoupon
components["schemas"]["OrderStateItem"]OrderStateItem
components["schemas"]["OrderAddress"]OrderAddress
components["schemas"]["OrderPaymentEvent"]OrderPaymentEvent
components["schemas"]["MarketplaceOrderPayment"]MarketplaceOrderPayment

OpenAPI Schema ​

json
{
  "title": "OrderState",
  "description": "An order as its events carry it: its status, totals, items, addresses and payments, the customer's contact (`customer_email`, `customer_phone`), who cancelled the order, and the KYC and ERP ledger details recorded when the merchant approved it.",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/OrderState",
    "description": "API reference for the OrderState schema"
  },
  "required": [
    "order_number",
    "order_date",
    "status",
    "payment_status",
    "payment_success_date",
    "customer_note",
    "is_promotion_applied",
    "promotion_discount_amount",
    "promotion_discount_percent",
    "is_coupon_applied",
    "coupon_code",
    "coupon_discount_amount",
    "coupon_discount_percent",
    "applied_promotions",
    "applied_coupons",
    "promotion_savings",
    "coupon_savings",
    "other_savings",
    "total_savings",
    "on_subscription",
    "subtotal",
    "subtotal_including_tax",
    "shipping_estimated_cost",
    "shipping_discount_amount",
    "shipping_amount",
    "shipping_tax_rate",
    "shipping_tax_amount",
    "shipping_amount_including_tax",
    "estimated_delivery_days",
    "handling_charge_excluding_tax",
    "handling_charge_tax_amount",
    "handling_charge_including_tax",
    "total_tax",
    "grand_total",
    "loyalty_points_earned",
    "loyalty_points_redeemed",
    "credit_balance_used",
    "to_be_paid",
    "order_items_count",
    "order_items",
    "billing_address",
    "shipping_address",
    "currency",
    "metadata",
    "is_cancellation_allowed",
    "cancellation_refund_details",
    "feedback",
    "cart_id",
    "coupon_id",
    "cancellation_reason",
    "shipping_provider_id",
    "courier_company_id",
    "shipping_provider_name",
    "courier_company_name",
    "items_tax_amount",
    "fulfillment_type",
    "sales_channel",
    "loyalty_point_eligible_amount",
    "payments",
    "customer_email",
    "customer_phone",
    "cancelled_by",
    "kyc_details",
    "erp_ledger"
  ],
  "properties": {
    "order_number": {
      "description": "Unique, human-readable order identifier used across all order endpoints.",
      "type": "string"
    },
    "order_date": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "description": "Current fulfillment status of the order. Progresses from `confirmed` through shipping stages to `complete`; a collect-in-store order with nothing to ship is `complete` as soon as it is paid, unless it was already accepted on the customer's credit line (it then stays `confirmed`). `pending` while it awaits payment, and `payment_failed` once every payment attempt failed (a payment retry reopens it). An order with one shipment can also take that shipment's `schedule_requested`, `processing`, `sent_to_store`, `ready_to_collect` or `lost`.",
      "type": "string",
      "enum": [
        "draft",
        "awaiting_approval",
        "confirmed",
        "partially_scheduled",
        "awaiting_shipment",
        "shipped",
        "partially_shipped",
        "undelivered",
        "partially_undelivered",
        "return_to_origin",
        "partially_return_to_origin",
        "complete",
        "partially_delivered",
        "cancelled",
        "pending",
        "schedule_requested",
        "payment_failed",
        "sent_to_store",
        "ready_to_collect",
        "processing",
        "lost"
      ]
    },
    "payment_status": {
      "description": "The order's payment status. `debit_scheduled` and `collection_due`: the order is on the customer's credit line, to be debited from their bank account by NACH mandate, or collected later. `refund_initiated` and `refunded`: refunds covering what was paid are on their way, or done. `manual_review`: the payment is being reviewed.",
      "type": "string",
      "enum": [
        "pending",
        "success",
        "failed",
        "partially_paid",
        "refund_initiated",
        "refunded",
        "debit_scheduled",
        "collection_due",
        "manual_review"
      ]
    },
    "payment_success_date": {
      "type": [
        "string",
        "null"
      ]
    },
    "customer_note": {
      "type": [
        "string",
        "null"
      ]
    },
    "is_promotion_applied": {
      "type": "boolean"
    },
    "promotion_discount_amount": {
      "type": "number",
      "format": "double"
    },
    "promotion_discount_percent": {
      "type": [
        "number",
        "null"
      ],
      "format": "double"
    },
    "is_coupon_applied": {
      "type": "boolean"
    },
    "coupon_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "coupon_discount_amount": {
      "type": "number",
      "format": "double"
    },
    "coupon_discount_percent": {
      "type": [
        "number",
        "null"
      ],
      "format": "double"
    },
    "applied_promotions": {
      "description": "Information about the promotional offers that have been applied to the cart.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AppliedPromotion"
      }
    },
    "applied_coupons": {
      "description": "This key provides details about the savings in cart after coupon have been applied to the cart.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AppliedCoupon"
      }
    },
    "promotion_savings": {
      "description": "Total savings from auto-applied promotions.",
      "type": "number",
      "format": "float",
      "minimum": 0
    },
    "coupon_savings": {
      "description": "Total savings from the applied coupon code.",
      "type": "number",
      "format": "float",
      "minimum": 0
    },
    "other_savings": {
      "description": "Total savings from loyalty points, credit balance, and other non-promotion/coupon discounts.",
      "type": "number",
      "format": "float",
      "minimum": 0
    },
    "total_savings": {
      "description": "Combined savings across promotions, coupons, and other discounts.",
      "type": "number",
      "format": "float",
      "minimum": 0
    },
    "on_subscription": {
      "type": "boolean"
    },
    "subtotal": {
      "type": "number",
      "format": "double"
    },
    "subtotal_including_tax": {
      "type": "number",
      "format": "double"
    },
    "shipping_estimated_cost": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "shipping_discount_amount": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "shipping_amount": {
      "type": "number",
      "format": "double"
    },
    "shipping_tax_rate": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "shipping_tax_amount": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "shipping_amount_including_tax": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "estimated_delivery_days": {
      "type": [
        "integer",
        "null"
      ]
    },
    "handling_charge_excluding_tax": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "handling_charge_tax_amount": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "handling_charge_including_tax": {
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "total_tax": {
      "type": "number",
      "format": "double"
    },
    "grand_total": {
      "type": "number",
      "format": "double"
    },
    "loyalty_points_earned": {
      "type": "number",
      "minimum": 0
    },
    "loyalty_points_redeemed": {
      "type": "number",
      "minimum": 0
    },
    "credit_balance_used": {
      "type": "number"
    },
    "to_be_paid": {
      "type": "number",
      "format": "double"
    },
    "order_items_count": {
      "type": "integer"
    },
    "order_items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrderStateItem"
      }
    },
    "billing_address": {
      "$ref": "#/components/schemas/OrderAddress"
    },
    "shipping_address": {
      "$ref": "#/components/schemas/OrderAddress"
    },
    "currency": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "code": {
          "type": "string"
        },
        "symbol": {
          "type": "string"
        }
      }
    },
    "metadata": {
      "description": "Additional metadata associated with the order: its point-of-sale details and its custom metadata (under `custom_metadata`). `null` when the order has none.",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "pos_user_id": {
          "description": "The point-of-sale user who placed the order; `null` when not placed at a point of sale.",
          "type": [
            "string",
            "null"
          ]
        },
        "pos_device_id": {
          "description": "The point-of-sale device the order was placed on; `null` when not placed at a point of sale.",
          "type": [
            "string",
            "null"
          ]
        },
        "origin_location_id": {
          "description": "The store location the order was placed at; `null` when not set.",
          "type": [
            "string",
            "null"
          ]
        },
        "custom_metadata": {
          "description": "The custom metadata given for the order.",
          "type": [
            "object",
            "null"
          ]
        }
      },
      "required": [
        "pos_user_id",
        "pos_device_id",
        "origin_location_id",
        "custom_metadata"
      ]
    },
    "is_cancellation_allowed": {
      "description": "Whether the order is eligible for cancellation. Only show the cancel action in your UI when this is `true`.",
      "type": "boolean"
    },
    "cancellation_refund_details": {
      "description": "Breakdown of the refund the customer would receive upon cancellation.",
      "type": "object",
      "properties": {
        "loyalty_point": {
          "description": "loyalty point redeemed will be rollbacked and credited to user account.",
          "type": "number"
        },
        "refundable_amount": {
          "description": "amount that will be refunded to customer.",
          "type": "number"
        },
        "cancellation_charges": {
          "description": "amount deducted from paid amount.",
          "type": "number"
        },
        "cancellation_charges_reason": {
          "description": "reason for cancellation charges.",
          "type": "string"
        },
        "payment_mode": {
          "description": "payment mode for refund.",
          "type": "string",
          "enum": [
            "original-payment-mode",
            "bank-transfer",
            "nach-mandate"
          ]
        }
      }
    },
    "feedback": {
      "type": [
        "string",
        "null"
      ]
    },
    "cart_id": {
      "description": "ULID of the cart this order was created from. `null` if unavailable.",
      "type": [
        "string",
        "null"
      ]
    },
    "coupon_id": {
      "description": "ID of the applied coupon. `null` when no coupon is applied.",
      "type": [
        "string",
        "null"
      ]
    },
    "cancellation_reason": {
      "description": "Reason the order was cancelled. `null` when not cancelled.",
      "type": [
        "string",
        "null"
      ]
    },
    "shipping_provider_id": {
      "description": "Order-level shipping provider ID. `null` until resolved.",
      "type": [
        "string",
        "null"
      ]
    },
    "courier_company_id": {
      "description": "Order-level courier company ID. `null` until resolved.",
      "type": [
        "string",
        "null"
      ]
    },
    "shipping_provider_name": {
      "description": "Order-level shipping provider name. Always `null`: the provider is resolved per shipment.",
      "type": [
        "string",
        "null"
      ]
    },
    "courier_company_name": {
      "description": "Order-level courier company name. Always `null`: the courier is resolved per shipment.",
      "type": [
        "string",
        "null"
      ]
    },
    "fulfillment_type": {
      "description": "Fulfillment type for the order (e.g. `delivery`, `collect-in-store`).",
      "type": "string"
    },
    "items_tax_amount": {
      "description": "Total tax amount for the order items.",
      "type": "number",
      "format": "double",
      "minimum": 0
    },
    "loyalty_point_eligible_amount": {
      "description": "Order amount eligible for loyalty-point earning.",
      "type": "number"
    },
    "sales_channel": {
      "description": "The sales channel the order was placed through: its `id` and `type` (e.g. `web`, `app`, `pos`), each `null` when not recorded.",
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ]
        },
        "type": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "type"
      ]
    },
    "payments": {
      "description": "The order's refunds, then its payments. A seller's copy of a marketplace order has one entry standing for the marketplace order's payment.",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/OrderPaymentEvent"
          },
          {
            "$ref": "#/components/schemas/MarketplaceOrderPayment"
          }
        ]
      }
    },
    "customer_email": {
      "description": "The customer's email: the order's contact email, else its billing or shipping address's.",
      "type": [
        "string",
        "null"
      ]
    },
    "customer_phone": {
      "description": "The customer's phone number: the order's contact phone, else its billing or shipping address's.",
      "type": [
        "string",
        "null"
      ]
    },
    "cancelled_by": {
      "description": "Who cancelled the order: `customer`, `system` (cancelled automatically, e.g. when left unpaid) or `admin:` followed by the admin's email. `null` when not cancelled, or cancelled through its shipments.",
      "type": [
        "string",
        "null"
      ]
    },
    "kyc_details": {
      "description": "The customer's KYC documents and customer group, recorded when the merchant approved the order. `null` until then, or when none were recorded.",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "documents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "document_type": {
                "type": "string",
                "enum": [
                  "gst",
                  "pan",
                  "drug_license",
                  "drug_license2"
                ]
              },
              "document_number": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "is_verified": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "is_mandatory": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "is_attachment_required": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          }
        },
        "customer_group": {
          "description": "The customer's group; empty when they have none.",
          "type": "string"
        }
      }
    },
    "erp_ledger": {
      "description": "The customer's ledger in the store's ERP that the order is booked to, recorded when the merchant approved the order. `null` when none is kept for it.",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "service_provider_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "service_provider_slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "service_provider_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "external_ledger_id": {
          "description": "The ledger's id in the ERP.",
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: