> ## Documentation Index > Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt > Use this file to discover all available pages before exploring further. # Orders and Invoices: Nymble Commerce's Full Commerce Lifecycle > Understand how Nymble Commerce flows from cart to order to invoice, including order types, invoice states, payment recording, and refund workflows. Nymble Commerce provides a complete commerce lifecycle — from shopping cart through order placement, invoice generation, payment collection, and refunds. Every step is API-driven and auditable, so you can build custom storefronts, assisted-ordering tools, and ERP integrations on top of a consistent, structured workflow. ## Order model An order captures the full context of a purchase: who bought it, what they bought, at what price, and under what terms. | Field | Type | Description | | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | Nymble Commerce's internal order ID. | | `OrderNumber` | string | Human-readable order number, auto-generated on creation. | | `OrganizationId` | string | The owning organization (resolved from your JWT). | | `OrderType` | string | Classification of the order — see [Order types](#order-types). | | `PONumber` | string | Customer's purchase order number for their records. | | `PriceTier` | string | The price tier active at time of order (e.g. `"Wholesale"`). | | `CurrencyCode` | string | ISO currency code for the order (e.g. `"USD"`). | | `Customer` | object | Snapshot of the customer at time of order: `CustomerNumber`, `CompanyName`, `CompanyEmail`, billing and shipping addresses. | | `Items` | array | Line items — see below. | | `ShippingDetails` | object | Shipping method, total, and formatted total. | | `PrimarySalesRep` | object | The rep primarily responsible for this order (`RepNumber`, `FirstName`, `LastName`, `Email`, `PhoneNumber`). | | `TakenBySalesRep` | object | The rep who physically entered the order, if different from the primary rep (e.g. at a trade show). | | `OrderStatus` | string | Current status of the order (e.g. `"Pending"`, `"Processing"`, `"Shipped"`, `"Completed"`). | | `Channel` | string | Where the order originated — e.g. `"Web"`, `"Phone"`, `"TradeShow"`, `"Import"`. | | `Terms` | string | Payment terms for this order (e.g. `"Net30"`). | | `Notes` | string | Internal notes on the order. | | `Tax` | decimal | Tax amount. | | `TaxFormatted` | string | Formatted tax string including currency symbol (e.g. `"$3.50"`). | | `Subtotal` | decimal | Pre-tax, pre-shipping subtotal. | | `SubtotalFormatted` | string | Formatted subtotal string. | | `OrderTotal` | decimal | Grand total including tax, shipping, and any discounts. | | `OrderTotalFormatted` | string | Formatted grand total string. | | `Discount` | object | Order-level discount applied (`Code`, `Type`, `Value`, `Description`). | | `DiscountAmount` | decimal | Computed discount amount. | | `DiscountAmountFormatted` | string | Formatted discount amount string. | | `ExternalId` | string | Your identifier for this order in an external system. | | `OriginationCartId` | string | The cart ID this order was created from, if applicable. | | `OrderDate` | datetime | When the order was placed. | | `CreatedAt` | datetime | Record creation timestamp. | | `UpdatedAt` | datetime | Last update timestamp. | ### Line item fields Each object in the `Items` array represents one product on the order: | Field | Type | Description | | ------------------------- | ------- | ----------------------------------------------- | | `Sku` | string | Product SKU. | | `ProductName` | string | Product name at time of order. | | `ExternalId` | string | Product's external ID at time of order. | | `Quantity` | integer | Quantity ordered. | | `MinimumOrderQuantity` | integer | MOQ enforced at time of order. | | `QuantityIncrement` | integer | Quantity step size enforced at time of order. | | `Price` | decimal | Unit price at time of order. | | `PriceFormatted` | string | Formatted unit price string. | | `SubTotal` | decimal | `Price × Quantity` before line-level discounts. | | `SubTotalFormatted` | string | Formatted subtotal string. | | `Discount` | object | Line-item discount, if applied. | | `DiscountAmount` | decimal | Computed discount amount for this line. | | `DiscountAmountFormatted` | string | Formatted discount amount string. | ### Example: creating an order ```json theme={null} POST https://api.achievemomentum.com/api/orders { "Customer": { "CustomerNumber": "CUST-0042", "CompanyName": "Acme Wholesale Ltd.", "CompanyEmail": "orders@acmewholesale.com" }, "OrderType": "Standard", "PONumber": "PO-2024-8821", "PriceTier": "Wholesale", "CurrencyCode": "USD", "PrimarySalesRep": { "RepNumber": "REP-007" }, "Items": [ { "Sku": "WDG-100-BLU", "Quantity": 24, "Price": 18.50 } ], "Terms": "Net30", "Channel": "Web" } ``` ## Order types The `OrderType` field classifies how an order was initiated. You can define values that suit your workflow — common examples include: | Type | Description | | ---------- | ---------------------------------------------------------------------------------- | | `Standard` | A regular customer-initiated order through your storefront or customer portal. | | `Assisted` | An order entered by a sales rep on behalf of a customer (phone, trade show, etc.). | | `Import` | A bulk order imported from an ERP or external system. | | `Sample` | A sample or trial order with special handling. | Use the `Channel` field alongside `OrderType` to capture additional context about where and how an order was received (e.g. `Channel: "TradeShow"` with `OrderType: "Assisted"`). ## Order lifecycle Orders flow through a predictable sequence from cart to fulfilled invoice: ```text theme={null} Shopping Cart │ ▼ Order Created ──── OrderStatus: "Pending" │ ▼ Invoice Generated ── Status: "Draft" or "Issued" │ ├──── Payment Received ──── Status: "PartiallyPaid" → "Paid" │ └──── Void / Cancel ──────── Status: "Voided" or "Cancelled" ``` Once an order is created, Nymble Commerce can generate one or more invoices against it. A single order can have multiple invoices (e.g. for split shipments), and the `OrderInvoiceSummaryDto` tracks fulfillment status across all invoices. ## Invoice model An invoice is the financial record of what a customer owes for an order (or part of an order). | Field | Type | Description | | ----------------- | -------- | ------------------------------------------------------------------ | | `Id` | string | Internal invoice ID. | | `InvoiceNumber` | string | Human-readable invoice number. | | `OrderId` | string | The order this invoice was generated from. | | `OrderNumber` | string | The associated order number. | | `ExternalId` | string | Your identifier for this invoice in an external system. | | `Customer` | object | Customer snapshot at time of invoicing. | | `PrimarySalesRep` | object | Sales rep associated with this invoice. | | `PONumber` | string | Customer's purchase order number. | | `InvoiceDate` | datetime | Date the invoice was issued. | | `DueDate` | datetime | Payment due date. | | `Terms` | string | Payment terms (e.g. `"Net30"`). | | `CurrencyCode` | string | ISO currency code. | | `Status` | string | Current invoice state — see below. | | `Items` | array | Line items invoiced (Sku, ProductName, Quantity, Price, SubTotal). | | `Payments` | array | List of payments recorded against this invoice. | | `Tax` | decimal | Tax amount. | | `Subtotal` | decimal | Pre-tax subtotal. | | `Discount` | object | Invoice-level discount (`Code`, `Type`, `Value`, `Description`). | | `DiscountAmount` | decimal | Computed discount amount. | | `InvoiceTotal` | decimal | Grand total of the invoice. | | `AmountPaid` | decimal | Total payments collected so far. | | `Balance` | decimal | Remaining amount due (`InvoiceTotal − AmountPaid`). | | `Notes` | string | Internal notes. | ### Invoice status states | Status | Description | | --------------- | ----------------------------------------------------------------------------------- | | `Draft` | Invoice created but not yet sent to the customer. | | `Issued` | Invoice has been issued; payment is expected. | | `PartiallyPaid` | One or more payments recorded, but `Balance > 0`. | | `Paid` | Invoice is fully paid. `Balance = 0`. | | `Voided` | Invoice was voided before payment. Removed from accounts receivable. | | `Cancelled` | Invoice was cancelled. The record is preserved but the invoice is no longer active. | ## Payment recording Nymble Commerce distinguishes between two payment flows: * **Online payment** — the customer completes payment through a connected payment provider (e.g. credit card at checkout). Nymble Commerce updates the invoice status automatically when the provider webhook fires. * **Offline / manual payment** — you record a payment against an invoice manually (e.g. EFT, cheque, cash). Use the `POST /api/invoices/{id}/payments` endpoint to record the payment amount, method, date, and reference number. Each `Payment` object on an invoice includes: | Field | Description | | -------------------------- | ---------------------------------------------------------------- | | `Amount` | The payment amount. | | `AmountFormatted` | Formatted payment amount string including currency symbol. | | `CurrencyCode` | ISO currency code for this payment. | | `Method` | How payment was made (e.g. `"CreditCard"`, `"EFT"`, `"Cheque"`). | | `Status` | Payment status (e.g. `"Completed"`, `"Pending"`). | | `PaymentDate` | When the payment was made or received. | | `Reference` | Cheque number, bank reference, or transaction ID. | | `Notes` | Optional free-text notes on this payment. | | `CardType` / `Last4Digits` | For card payments, the card brand and last 4 digits. | | `RefundedAmount` | Total amount refunded against this payment. | | `NetAmount` | Net amount after refunds (`Amount − RefundedAmount`). | | `Refunds` | List of refund records applied against this payment. | For full payment provider integration and hosted checkout details, see the [Payments and Checkout guide](/guides/payments-checkout). ## Discounts Discounts in Nymble Commerce can be applied at the **invoice level** or at the **line item level**. An invoice-level discount has: * `Code` — a discount code string, if applicable. * `Type` — either `"Fixed"` (a flat amount off) or `"Percentage"` (a percentage off the subtotal). * `Value` — the discount amount or percentage. * `Description` — a human-readable label shown on the invoice. The computed `DiscountAmount` and `DiscountAmountFormatted` fields reflect the actual dollar amount deducted, regardless of discount type. ## Refunds and voids Nymble Commerce supports two distinct reversal operations: | Operation | When to use | Effect | | ---------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **Void** | Invoice is unpaid and needs to be cancelled before payment. | Removes the invoice from accounts receivable. The record is marked `Voided`. | | **Cancel** | Invoice needs to be marked inactive but preserved in records. | Marks the invoice `Cancelled`. The record is retained for audit purposes. | | **Refund** | Invoice is fully or partially paid and payment needs to be reversed. | Creates a refund record against the original payment. The invoice `Balance` is adjusted. | **Void vs Cancel** — voiding an invoice removes it from your accounts receivable totals, as if the obligation never existed. Cancelling marks the invoice inactive but leaves it visible in reporting. Choose void when the sale is being fully reversed; choose cancel when you need to preserve the paper trail. Both operations are **permanent** and cannot be undone.