Skip to content

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;
        };
        /**
         * OrderAddress
         * @description A billing or shipping address as recorded on the order: a copy made when the order was placed, so later changes to the customer's saved addresses don't alter it. Its fields are `null` when the order was placed without them (e.g. at a point of sale).
         */
}

Component References ​

ReferenceResolves To
components["schemas"]["AppliedPromotion"]AppliedPromotion
components["schemas"]["AppliedCoupon"]AppliedCoupon
components["schemas"]["FulfillmentPreference"]FulfillmentPreference
components["schemas"]["OrderItem"]OrderItem
components["schemas"]["OrderAddress"]OrderAddress

OpenAPI Schema ​

json
{
  "title": "Order",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/Order",
    "description": "API reference for the Order schema"
  },
  "required": [
    "applied_promotions",
    "applied_coupons"
  ],
  "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"
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: