Orders and Invoices: Nymble Commerce's Full Commerce Lifecycle

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.
`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

POST https://api.achievemomentum.com/api/orders

{
  "Customer": {
    "CustomerNumber": "CUST-0042",
    "CompanyName": "Acme Wholesale Ltd.",
    "CompanyEmail": "[email protected]"
  },
  "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:

 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.

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.

​Order model

​Line item fields

​Example: creating an order

​Order types

​Order lifecycle

​Invoice model

​Invoice status states

​Payment recording

​Discounts

​Refunds and voids

Order model

Line item fields

Example: creating an order

Order types

Order lifecycle

Invoice model

Invoice status states

Payment recording

Discounts

Refunds and voids