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