Order
Type: schema
TypeScript Definition
typescript
Order: {{
/** @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 Current payment status. Poll `/orders/{order_number}/payment-status` after a payment attempt until this is `success` or `failed`. `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.
* @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 */
item_total_tax?: 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;
/** @description How the customer wants to receive the order. `null` when the order has no fulfillment preference (e.g. created without a checkout). */
fulfillment_preference?: components["schemas"]["FulfillmentPreference"] | null;
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"]["OrderItem"][];
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 the custom metadata given at checkout as further keys. */
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;
} & {
[key: string]: string;
}) | 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. Only populated when `is_cancellation_allowed` is `true`. */
cancellation_refund_details?: {
/** @description loyalty point redeemed will be rollbacked and credited to user account. */
loyalty_point?: number;
/** @description What the customer gets back on cancellation: what the order's payments have left after its earlier refunds, refunds in progress included. Money held for an admin's review isn't included: it is refunded once the review releases it. */
refundable_amount?: number;
/** @description amount deducted from paid amount. */
cancellation_charges?: number;
/** @description reason for cancellation charges. */
cancellation_charges_reason?: string;
/**
* @description How the refund is paid: `bank-transfer` to the customer's bank account when a bank transfer (credit balance included) paid the order; `original-payment-mode`, back through the payment gateway, otherwise. A cash or other offline payment is handed back by the store in the way it was paid, in either mode, with no bank account needed for it.
* @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. Currently always `null` (resolved per shipment under `shipments[]`). */
shipping_provider_name?: string | null;
/** @description Order-level courier company name. Currently always `null` (resolved per shipment under `shipments[]`). */
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 (same concept as the legacy `item_total_tax`).
*/
items_tax_amount?: number;
/** @description Order amount eligible for loyalty-point earning. */
loyalty_point_eligible_amount?: number;
/** @description The sales channel the order belongs to. */
sales_channel?: {
id?: string | null;
name?: string | null;
type?: string | null;
};
/**
* Format: date-time
* @description Creation timestamp (ISO-8601).
*/
created_at?: string;
/**
* Format: date-time
* @description Last-modification timestamp (ISO-8601).
*/
modified_at?: string;
};
/** @enum {unknown} */
}Component References
| Reference | Resolves To |
|---|---|
components["schemas"]["AppliedPromotion"] | AppliedPromotion |
components["schemas"]["AppliedCoupon"] | AppliedCoupon |
components["schemas"]["FulfillmentPreference"] | FulfillmentPreference |
components["schemas"]["OrderItem"] | OrderItem |
components["schemas"]["OrderAddress"] | OrderAddress |
OpenAPI Schema
json
{
"type": "object",
"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": "Current payment status. Poll `/orders/{order_number}/payment-status` after a payment attempt until this is `success` or `failed`. `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.",
"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"
},
"item_total_tax": {
"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
},
"fulfillment_preference": {
"description": "How the customer wants to receive the order. `null` when the order has no fulfillment preference (e.g. created without a checkout).",
"oneOf": [
{
"$ref": "#/components/schemas/FulfillmentPreference"
},
{
"type": "null"
}
]
},
"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/OrderItem"
}
},
"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 the custom metadata given at checkout as further keys.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
},
"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"
]
}
}
},
"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. Only populated when `is_cancellation_allowed` is `true`.",
"type": "object",
"properties": {
"loyalty_point": {
"description": "loyalty point redeemed will be rollbacked and credited to user account.",
"type": "number"
},
"refundable_amount": {
"description": "What the customer gets back on cancellation: what the order's payments have left after its earlier refunds, refunds in progress included. Money held for an admin's review isn't included: it is refunded once the review releases it.",
"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": "How the refund is paid: `bank-transfer` to the customer's bank account when a bank transfer (credit balance included) paid the order; `original-payment-mode`, back through the payment gateway, otherwise. A cash or other offline payment is handed back by the store in the way it was paid, in either mode, with no bank account needed for it.",
"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. Currently always `null` (resolved per shipment under `shipments[]`).",
"type": [
"string",
"null"
]
},
"courier_company_name": {
"description": "Order-level courier company name. Currently always `null` (resolved per shipment under `shipments[]`).",
"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 (same concept as the legacy `item_total_tax`).",
"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 belongs to.",
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
]
}
}
},
"created_at": {
"description": "Creation timestamp (ISO-8601).",
"type": "string",
"format": "date-time"
},
"modified_at": {
"description": "Last-modification timestamp (ISO-8601).",
"type": "string",
"format": "date-time"
}
},
"externalDocs": {
"url": "https://llm-docs.commercengine.io/storefront/schemas/Order",
"description": "API reference for the Order schema"
},
"required": [
"applied_promotions",
"applied_coupons"
],
"title": "Order"
}Auto-generated from OpenAPI spec and TypeScript definitions