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
| Reference | Resolves 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