Skip to content

InvoiceState ​

Type: schema

Description ​

A sales invoice for a shipment, or for an order's digital items: one Commerce Engine generates (invoice_source default, invoice.* events) or one issued by the seller (seller, external_invoice.* events): by the seller, their ERP, or a seller store.

TypeScript Definition ​

typescript
InvoiceState: {{
            invoice_number: string;
            /** @description Invoice total: the invoice's own, or, when it has no totals of its own, computed from its lines (`subtotal` + `total_tax` + `shipping_amount` - `coupon_discount_amount`). */
            grand_total: number;
            /** @description The invoice number (same as `invoice_number`); the event's key. */
            invoice_id: string;
            /**
             * @description `seller` for a seller invoice; `default` for one Commerce Engine generates.
             * @enum {string}
             */
            invoice_source: "seller" | "default";
            /** Format: date */
            invoice_date: string | null;
            /** @description The order number (same as `order_number`). */
            order_id: string;
            order_number: string;
            /** @description The shipment's reference number (same as `reference_number`); `MS:`-prefixed on a seller store's copy of a marketplace shipment. `null` for an invoice of an order's digital items, which have no shipment. */
            shipment_id: string | null;
            /** @description Present when the shipment belongs to a marketplace. */
            marketplace_listing?: {
                marketplace_id: string;
            }[];
            /** @description Commerce Engine's id for the invoice. */
            invoice_record_id?: number;
            /** @description Same as `invoice_record_id`. */
            invoice_generation?: number;
            /** @description `printed` by default; `cancelled` on `external_invoice.cancelled`. */
            status?: string;
            reference_number?: string | null;
            warehouse_id?: string | null;
            /** @description The shipment's items, with quantity and free quantity. */
            shipment_items?: {
                product_id: string;
                variant_id: null | string;
                quantity: number;
                free_quantity: number;
            }[];
            /** @description The order's billing business name. */
            billing_business_name?: string | null;
            /** @description Item total before tax, from the invoice's own totals; not filled when it has none (`subtotal` always is). */
            sub_total?: number;
            /** @description Item total including tax. */
            sub_total_including_tax?: number;
            promotion_discount_amount?: number;
            /** @description Discount on the invoice: its own, or, when it has no totals of its own, its lines' coupon and promotion discounts. */
            coupon_discount_amount?: number;
            /** @description Loyalty-point value redeemed against this invoice. */
            loyalty_point_redeemed?: number;
            shipping_amount?: number;
            shipping_amount_including_tax?: number;
            /** @description The seller who issued the invoice. */
            seller_details?: null | {
                id: string;
                name?: string;
            };
            /** @description GST e-invoice Invoice Reference Number. */
            irn_number?: null | string;
            /** @description GST e-invoice acknowledgement number. */
            ack_number?: string | null;
            /**
             * Format: date-time
             * @description GST e-invoice acknowledgement date.
             */
            ack_date?: string | null;
            /** @description GST e-invoice signed QR code. */
            signed_qr_code?: string | null;
            /** @description Gate-pass barcode from the seller's ERP. */
            gatepass_barcode?: string | null;
            /** @description Invoice lines: the SKU, quantities and price of each invoiced item. */
            items?: {
                sku: string;
                order_item_id?: string;
                /** @description Invoiced quantity. */
                qty: string;
                /** @description Batch number of the goods, from the seller's ERP. */
                batch_no?: string | null;
                /** @description Expiry of the batch, from the seller's ERP. */
                expiry?: string | null;
                /** @description Free (scheme) quantity on top of `qty`. */
                free_qty?: string | null;
                /** @description The line's name. */
                item_name?: string | null;
                listing_price?: number;
                selling_price?: number;
                selling_price_excluding_tax?: number;
                tax_rate?: number;
                tax_type?: string;
                product_name?: string;
                product_image_url?: string | null;
                hsncode?: string | null;
                coupon_discount_amount?: number;
                promotion_discount_amount?: number;
                /** @description The line's taxable value: `selling_price` x `qty` less its coupon and promotion discounts. */
                amount?: number;
            }[];
            created_at?: string;
            modified_at?: string;
            billing_address?: {
                first_name: string;
                last_name: null | string;
                business_name: string | null;
                phone: null | string;
                country_code: null | string;
                address_line1: null | string;
                address_line2: string | null;
                landmark: string | null;
                pincode: null | string;
                city: string;
                state: null | string;
                country: null | string;
                gstin: string | null;
                email: null | string;
                is_email_verified: boolean;
                is_phone_verified: boolean;
            };
            shipping_address?: {
                first_name: string;
                last_name: null | string;
                business_name: string | null;
                phone: null | string;
                country_code: null | string;
                address_line1: null | string;
                address_line2: string | null;
                landmark: string | null;
                pincode: null | string;
                city: string;
                state: null | string;
                country: null | string;
                gstin: string | null;
                email: null | string;
                is_email_verified: boolean;
                is_phone_verified: boolean;
            };
            coupon_code?: null | string;
            /** @description Tax per rate across `items`. `cgst` and `sgst` are each half the tax and `igst` the whole; all three are given whatever the place of supply, so use the ones that apply to it. */
            tax_summary?: {
                tax_rate: number;
                taxable_value: number;
                cgst: number;
                sgst: number;
                igst: number;
            }[];
            /** @description Item total before tax: `sub_total`, or, when the invoice has no totals of its own, the sum of its lines' `amount`. */
            subtotal?: number;
            /** @description Total tax: `sub_total_including_tax` - `sub_total`, or, when the invoice has no totals of its own, the tax on its lines. */
            total_tax?: number;
        };
        /**
         * ItemMarketplaceListing
         * @description A product's or variant's listing on a marketplace the store sells through: how it is listed there.
         */
}

OpenAPI Schema ​

json
{
  "title": "InvoiceState",
  "description": "A sales invoice for a shipment, or for an order's digital items: one Commerce Engine generates (`invoice_source` `default`, `invoice.*` events) or one issued by the seller (`seller`, `external_invoice.*` events): by the seller, their ERP, or a seller store.",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/InvoiceState",
    "description": "API reference for the InvoiceState schema"
  },
  "required": [
    "grand_total",
    "invoice_date",
    "invoice_id",
    "invoice_number",
    "invoice_source",
    "order_id",
    "order_number",
    "shipment_id"
  ],
  "properties": {
    "invoice_number": {
      "type": "string"
    },
    "grand_total": {
      "description": "Invoice total: the invoice's own, or, when it has no totals of its own, computed from its lines (`subtotal` + `total_tax` + `shipping_amount` - `coupon_discount_amount`).",
      "type": "number"
    },
    "invoice_id": {
      "description": "The invoice number (same as `invoice_number`); the event's key.",
      "type": "string"
    },
    "invoice_source": {
      "description": "`seller` for a seller invoice; `default` for one Commerce Engine generates.",
      "type": "string",
      "enum": [
        "seller",
        "default"
      ]
    },
    "invoice_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "order_id": {
      "description": "The order number (same as `order_number`).",
      "type": "string"
    },
    "order_number": {
      "type": "string"
    },
    "shipment_id": {
      "description": "The shipment's reference number (same as `reference_number`); `MS:`-prefixed on a seller store's copy of a marketplace shipment. `null` for an invoice of an order's digital items, which have no shipment.",
      "type": [
        "string",
        "null"
      ]
    },
    "marketplace_listing": {
      "description": "Present when the shipment belongs to a marketplace.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "marketplace_id": {
            "type": "string"
          }
        },
        "required": [
          "marketplace_id"
        ]
      }
    },
    "invoice_record_id": {
      "description": "Commerce Engine's id for the invoice.",
      "type": "integer"
    },
    "invoice_generation": {
      "description": "Same as `invoice_record_id`.",
      "type": "integer"
    },
    "status": {
      "description": "`printed` by default; `cancelled` on `external_invoice.cancelled`.",
      "type": "string"
    },
    "reference_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "warehouse_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "shipment_items": {
      "description": "The shipment's items, with quantity and free quantity.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "variant_id": {
            "type": [
              "null",
              "string"
            ]
          },
          "quantity": {
            "type": "integer"
          },
          "free_quantity": {
            "type": "integer"
          }
        },
        "required": [
          "free_quantity",
          "product_id",
          "quantity",
          "variant_id"
        ]
      }
    },
    "billing_business_name": {
      "description": "The order's billing business name.",
      "type": [
        "string",
        "null"
      ]
    },
    "sub_total": {
      "description": "Item total before tax, from the invoice's own totals; not filled when it has none (`subtotal` always is).",
      "type": "number"
    },
    "sub_total_including_tax": {
      "description": "Item total including tax.",
      "type": "number"
    },
    "promotion_discount_amount": {
      "type": "number"
    },
    "coupon_discount_amount": {
      "description": "Discount on the invoice: its own, or, when it has no totals of its own, its lines' coupon and promotion discounts.",
      "type": "number"
    },
    "loyalty_point_redeemed": {
      "description": "Loyalty-point value redeemed against this invoice.",
      "type": "number"
    },
    "shipping_amount": {
      "type": "number"
    },
    "shipping_amount_including_tax": {
      "type": "number"
    },
    "seller_details": {
      "description": "The seller who issued the invoice.",
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        }
      ]
    },
    "irn_number": {
      "description": "GST e-invoice Invoice Reference Number.",
      "type": [
        "null",
        "string"
      ]
    },
    "ack_number": {
      "description": "GST e-invoice acknowledgement number.",
      "type": [
        "string",
        "null"
      ]
    },
    "ack_date": {
      "description": "GST e-invoice acknowledgement date.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "signed_qr_code": {
      "description": "GST e-invoice signed QR code.",
      "type": [
        "string",
        "null"
      ]
    },
    "gatepass_barcode": {
      "description": "Gate-pass barcode from the seller's ERP.",
      "type": [
        "string",
        "null"
      ]
    },
    "items": {
      "description": "Invoice lines: the SKU, quantities and price of each invoiced item.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string"
          },
          "order_item_id": {
            "type": "string"
          },
          "qty": {
            "description": "Invoiced quantity.",
            "type": "string"
          },
          "batch_no": {
            "description": "Batch number of the goods, from the seller's ERP.",
            "type": [
              "string",
              "null"
            ]
          },
          "expiry": {
            "description": "Expiry of the batch, from the seller's ERP.",
            "type": [
              "string",
              "null"
            ]
          },
          "free_qty": {
            "description": "Free (scheme) quantity on top of `qty`.",
            "type": [
              "string",
              "null"
            ]
          },
          "item_name": {
            "description": "The line's name.",
            "type": [
              "string",
              "null"
            ]
          },
          "listing_price": {
            "type": "number"
          },
          "selling_price": {
            "type": "number"
          },
          "selling_price_excluding_tax": {
            "type": "number"
          },
          "tax_rate": {
            "type": "number"
          },
          "tax_type": {
            "type": "string"
          },
          "product_name": {
            "type": "string"
          },
          "product_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "hsncode": {
            "type": [
              "string",
              "null"
            ]
          },
          "coupon_discount_amount": {
            "type": "number"
          },
          "promotion_discount_amount": {
            "type": "number"
          },
          "amount": {
            "description": "The line's taxable value: `selling_price` x `qty` less its coupon and promotion discounts.",
            "type": "number"
          }
        },
        "required": [
          "qty",
          "sku"
        ]
      }
    },
    "created_at": {
      "type": "string"
    },
    "modified_at": {
      "type": "string"
    },
    "billing_address": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": [
            "null",
            "string"
          ]
        },
        "business_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "null",
            "string"
          ]
        },
        "country_code": {
          "type": [
            "null",
            "string"
          ]
        },
        "address_line1": {
          "type": [
            "null",
            "string"
          ]
        },
        "address_line2": {
          "type": [
            "string",
            "null"
          ]
        },
        "landmark": {
          "type": [
            "string",
            "null"
          ]
        },
        "pincode": {
          "type": [
            "null",
            "string"
          ]
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": [
            "null",
            "string"
          ]
        },
        "country": {
          "type": [
            "null",
            "string"
          ]
        },
        "gstin": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "null",
            "string"
          ]
        },
        "is_email_verified": {
          "type": "boolean"
        },
        "is_phone_verified": {
          "type": "boolean"
        }
      },
      "required": [
        "address_line1",
        "address_line2",
        "business_name",
        "city",
        "country",
        "country_code",
        "email",
        "first_name",
        "gstin",
        "is_email_verified",
        "is_phone_verified",
        "landmark",
        "last_name",
        "phone",
        "pincode",
        "state"
      ]
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": [
            "null",
            "string"
          ]
        },
        "business_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "null",
            "string"
          ]
        },
        "country_code": {
          "type": [
            "null",
            "string"
          ]
        },
        "address_line1": {
          "type": [
            "null",
            "string"
          ]
        },
        "address_line2": {
          "type": [
            "string",
            "null"
          ]
        },
        "landmark": {
          "type": [
            "string",
            "null"
          ]
        },
        "pincode": {
          "type": [
            "null",
            "string"
          ]
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": [
            "null",
            "string"
          ]
        },
        "country": {
          "type": [
            "null",
            "string"
          ]
        },
        "gstin": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "null",
            "string"
          ]
        },
        "is_email_verified": {
          "type": "boolean"
        },
        "is_phone_verified": {
          "type": "boolean"
        }
      },
      "required": [
        "address_line1",
        "address_line2",
        "business_name",
        "city",
        "country",
        "country_code",
        "email",
        "first_name",
        "gstin",
        "is_email_verified",
        "is_phone_verified",
        "landmark",
        "last_name",
        "phone",
        "pincode",
        "state"
      ]
    },
    "coupon_code": {
      "type": [
        "null",
        "string"
      ]
    },
    "tax_summary": {
      "description": "Tax per rate across `items`. `cgst` and `sgst` are each half the tax and `igst` the whole; all three are given whatever the place of supply, so use the ones that apply to it.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tax_rate": {
            "type": "number"
          },
          "taxable_value": {
            "type": "number"
          },
          "cgst": {
            "type": "number"
          },
          "sgst": {
            "type": "number"
          },
          "igst": {
            "type": "number"
          }
        },
        "required": [
          "cgst",
          "igst",
          "sgst",
          "tax_rate",
          "taxable_value"
        ]
      }
    },
    "subtotal": {
      "description": "Item total before tax: `sub_total`, or, when the invoice has no totals of its own, the sum of its lines' `amount`.",
      "type": "number"
    },
    "total_tax": {
      "description": "Total tax: `sub_total_including_tax` - `sub_total`, or, when the invoice has no totals of its own, the tax on its lines.",
      "type": "number"
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: