Cart Service

Back

For validation semantics (errors/warnings, the atomic upsert contract, preview/convert correlation) see the Cart Validation & Checkout — Frontend Integration Guide. This page covers the endpoints and session/merge mechanics only.

Overview

The Cart Service manages shopping carts and their line items. Carts support anonymous guest flows, authenticated user sessions, and seamless merge on login.

Each cart is identified by a client-generated GUID and can be associated with a user after login.

Cart types are seeded as follows:

All cart endpoints are [AllowAnonymous] with rate limiting applied per IP (AnonCart policy), except cart deletion which requires FullManage.

All operations are tenant-aware.

Database tables

• sales.Cart
• sales.CartItem
• ref.CartType

Endpoints

Back to Sales

GET

/api/v1/Cart

Returns a cart by its GUID or by user GUID.

Query parameters:

• guid (string, optional) — cart GUID
• userGuid (Guid, optional) — looks up the cart associated with the user

Behavior:

• Returns 404 if not found
• Only one of guid or userGuid should be supplied

Response:

• CartModel (includes Items list)

Authorization:

• [AllowAnonymous] — no token required

POST

/api/v1/Cart

Unified cart session endpoint — creates, claims, or merges a cart depending on the fields supplied.

Request body (CartSessionDTO):

• UserGuid (Guid?, optional) — authenticated user's GUID. If present, the request must be authenticated.
• CartTypeId (int?, optional) — cart type to assign on creation
• MergeFromGuid (string?, optional) — GUID of a guest cart to merge into the user's cart

Behavior modes:

Response:

• 200 OK — CartModel

Authorization:

• [AllowAnonymous] — but if UserGuid is provided the request must include a valid Bearer token

POST

/api/v1/Cart/items

Adds, updates, or removes cart items by cart GUID.

Request body (UpsertCartItemsDTO):

• Guid (string, required) — cart GUID
• Items (List, required) — items to upsert:
  • Sku (string, required) — product SKU
  • Quantity (int, required) — new quantity. Set to 0 or negative to remove the item.
  • UserId (long?, optional) — entity-user placing this line (customisation scoping)
  • Notes (string?, optional) — customisation notes

Behavior:

• An empty Items list deletes the entire cart
• Quantity <= 0 removes that item from the cart
• New additions are validated atomically — if any new SKU is unavailable/not allowed, the entire batch is rejected (nothing applied) and the response is 422 with a full CartModel body (operationError set, validation.rejectedAdditions populated). Updates/ removals of lines already in the cart are never blocked this way. See the frontend guide for the full contract.

Response:

• 200 OK — CartModel (success)
• 422 Unprocessable Entity — CartModel (batch rejected; still a full cart body)

Authorization:

• [AllowAnonymous] — no token required

POST

/api/v1/Cart/guid/{guid}/invalid-items/remove

Removes exactly the error-severity items excluded for the supplied EntityId, PriceListId, and DocumentTypeGuid context. Send all their CartItemId values as CartItemIds. The API revalidates before removal and returns 409 CartConcurrencyConflict if the set changed. Success returns the updated CartModel; valid items remain untouched.

POST

/api/v1/Cart/guid/{guid}/preview

Calculates prices, tax, and totals for a cart without creating a document.

Route parameters:

• guid (string, required) — cart GUID

Request body (PreviewCartRequest):

• EntityId (long, required) — customer entity to price against
• UserId (long?, optional) — user placing the order
• PriceListId (long?, optional) — price list to apply
• DocumentTypeGuid (string, required) — the document type the cart is for (e.g. "SALES_ORDER", "QUOTE")
• PromoCodes (string[]?, optional) — promo codes to evaluate for this request (see Promo codes)

Behavior:

• Resolves product prices using the given entity and price list
• Applies price tier fallback: uses the closest tier at or below the requested quantity
• Evaluates the promo codes at every discount level and reports each code's outcome
• Every submitted code that is not Applied becomes a cart-level warning in CartValidation.CartWarnings and changes CartValidation.Signature; the merged signature is saved on the cart
• Returns a fully calculated document preview without changing cart contents or creating a document; validation metadata on existing cart items may be refreshed

Response:

• 200 OK — DocumentModel (unsaved, Id = 0), with AppliedDiscounts and, when codes were sent, PromoCodes
• 400 Bad Request — CartPromoCodesInvalid (6053) if more than 10 codes are sent, or any code is longer than 100 characters

Authorization:

• [AllowAnonymous] — no token required

POST

/api/v1/Cart/guid/{guid}/convert

Converts a cart into a saved document. The cart is deleted on success.

Route parameters:

• guid (string, required) — cart GUID

Request body (ConvertCartRequest — extends PreviewCartRequest):

• EntityId (long, required) — customer entity
• UserId (long?, optional) — user placing the order
• PriceListId (long?, optional) — price list to apply
• DocumentTypeGuid (string, required) — target document type code (e.g. "SALES_ORDER", "QUOTE"). Determines document type and initial status
• PromoCodes (string[]?, optional) — promo codes to apply; send the same set the customer accepted at preview (see Promo codes)
• DocumentCategoryId (int?, optional) — document category FK
• BillingAddressSnapshots (DocumentBillingAddressSnapshotModel?, optional) — full billing address to stamp on the document
• ShippingAddressSnapshots (DocumentShippingAddressSnapshotModel, required) — full shipping address to stamp on the document
• Notes (string?, optional) — order notes
• PurchaseOrderRef (string?, optional) — customer PO reference
• AdditionalRef (string?, optional) — secondary reference
• Tags (string?, optional) — comma-separated tags
• Description (string?, optional) — document description
• ActionNotes (string?, optional) — internal action notes
• Other1 / Other2 / Other3 (string?, optional) — configurable fields
• OtherNotes (string?, optional) — additional notes
• IsBillingSameAsShipping (bool) — if true, billing snapshot is copied from shipping
• AcknowledgedValidationSignature (string?, optional) — current warning signature after explicit customer acceptance; a preview alone does not acknowledge warnings
• RequireAllItemsConvertible (bool, optional) — when true, reject with 409 / 6051 if any item is excluded by current validation

Behavior:

• Creates Document and DocumentLine records from cart contents
• Items with validation errors are excluded from the document, not a reason to refuse conversion — convert only fails if nothing in the cart is convertible (422 CartHasNoConvertibleItems). See the frontend guide for the full contract, including the warning-acknowledgement gate.
• The cart is priced first, then every submitted promo code that is not Applied is added as a cart-level warning and the signature recomputed. If there are active warnings and AcknowledgedValidationSignature does not match the recomputed signature, convert returns 409 CartValidationAcknowledgementRequired and nothing is saved. A code that applied at preview but is invalid at convert therefore blocks convert until the new signature is acknowledged. The document saved is exactly the one that was priced and checked
• Every applied discount is recorded in discount usage history with its real amount, inside the same transaction, and the promo outcomes are written to the audit log (Cart {guid} promo codes: SAVE10=Applied, FREESHIP=Invalid)
• Address snapshots are saved and linked to the document — they are immutable copies of the address at time of conversion, independent of any future address changes
• Prices are resolved using the same tier logic as preview
• WarehouseId is taken from the stock item associated with each variant
• Document status is determined by the target type's InitialStatusGuid configuration; falls back to NEW_ORDER if not set
• Source cart is deleted on success, atomically with document creation

Response:

• 201 Created — DocumentModel (fully populated, same shape as /api/v1/Documents/{id}), plus AppliedDiscounts and, when codes were sent, PromoCodes
• 400 Bad Request — CartPromoCodesInvalid (6053) for more than 10 codes or a code longer than 100 characters
• 422 Unprocessable Entity — CartHasNoConvertibleItems if nothing in the cart is convertible
• 409 Conflict — CartContainsExcludedItems if strict conversion encounters invalid items
• 409 Conflict — CartValidationAcknowledgementRequired if warnings (including promo code warnings) are active and the signature has not been acknowledged

Authorization:

• [AllowAnonymous] — no token required

DELETE

/api/v1/Cart/{id}

Deletes a cart by its internal numeric ID.

Route parameters:

• id (long, required) — cart identifier

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

Models

CartModel

Fields:

• Guid (type: string?) — client-assigned GUID (used for all cart operations)
• DateAdded (type: DateTime?) — creation timestamp
• DeviceId (type: string?) — device identifier
• UserId (type: long?) — associated user
• CartTypeId (type: int?) — FK to CartType
• DateLastUpdated (type: DateTime?) — last update timestamp
• Items (type: List<CartItemModel>?) — cart line items
• Validation (type: CartValidationModel?) — aggregate + per-item validation state (see frontend guide)
• OperationError (type: CartOperationError?) — set only on a rejected POST /items call

Note: Id is present in the DB but omitted from JSON responses. Each CartItemModel does include its own Id in JSON so preview cartItemId values can be joined back to cart rows.

CartItemPostDTO

Fields used when upserting items via POST /api/v1/Cart/items:

• Sku (type: string) — product SKU
• Quantity (type: int) — quantity (<= 0 removes the item)
• UserId (type: long?) — entity-user placing this line
• Notes (type: string?) — customisation notes

PreviewCartRequest

Fields used for preview and as base for convert:

• EntityId (type: long) — customer entity
• UserId (type: long?) — user placing the order
• PriceListId (type: long?) — price list to apply
• DocumentTypeGuid (type: string) — the document type the cart is for (e.g. "SALES_ORDER", "QUOTE"). Required by cart validation (422 CartValidationContextRequired when missing or unknown); on convert it also determines the document type and initial status
• PromoCodes (type: string[]?) — promo codes for this request only; see Promo codes

ConvertCartRequest

Extends PreviewCartRequest. Additional fields:

• DocumentCategoryId (type: int?) — document category FK
• BillingAddressSnapshots (type: DocumentBillingAddressSnapshotModel?) — billing address snapshot
• ShippingAddressSnapshots (type: DocumentShippingAddressSnapshotModel) — shipping address snapshot
• Notes (type: string?) — order notes
• PurchaseOrderRef (type: string?) — customer PO reference
• AdditionalRef (type: string?) — secondary reference
• Tags (type: string?) — comma-separated tags
• Description (type: string?) — document description
• ActionNotes (type: string?) — internal action notes
• Other1 / Other2 / Other3 (type: string?) — configurable fields
• OtherNotes (type: string?) — additional notes
• IsBillingSameAsShipping (type: bool) — copy billing from shipping
• AcknowledgedValidationSignature (type: string?) — the current cartValidation.signature after explicit customer acceptance; required once warning detection ships
• RequireAllItemsConvertible (type: bool) — rejects excluded items with 409 / 6051

DocumentAddressSnapshotModel

Used in both billing and shipping snapshot fields:

• Name (type: string?) — address name / company
• Line1 (type: string?) — street address line 1
• Line2 (type: string?) — street address line 2
• City (type: string?) — city
• StateRegion (type: string?) — state or region
• PostalCode (type: string?) — postal/ZIP code
• CountryCode (type: string?) — ISO country code
• Phone (type: string?) — phone number
• Email (type: string?) — email

Promo codes

• The cart stores no codes and there is no apply/remove-code endpoint. Send the full set of codes on every preview and convert; the frontend owns the "applied codes" state.
• Codes are trimmed, blanks are dropped and duplicates are removed case-insensitively (the first occurrence wins). More than 10 codes, or a code longer than 100 characters, is a 400.
• One bucket applies at every level: product, category and brand discounts on lines, and subtotal, shipping and order-total discounts. A code-gated discount becomes eligible when its code is in the bucket and is then validated as usual. One code may unlock several discounts.
• Code-unlocked and automatic discounts compete: the best value wins (the highest single amount, or the cumulative set when larger). A valid code that loses reports NotApplied.
• Bad codes never fail pricing; they are reported per code as Applied, NotApplied or Invalid (DocumentModel.PromoCodes), with no further reason.
• When the request has no entity, codes are not evaluated and every submitted code is Invalid.
• Each code that is not Applied adds a cart warning: PromoCodeNotApplied (Promo code {CODE} has not been applied.) or PromoCodeInvalid (Promo code {CODE} is not valid.), where {CODE} is the trimmed upper-case code. These are part of the validation signature, so convert needs the signature acknowledged.
• Documents derived from a converted cart (quote → order, order → invoice, sub-orders) keep the origin's subtotal and order-total discounts on recompute, and lines added later are priced with the origin's codes, validated live. Purchase orders inherit nothing.

Notes

• All cart endpoints are rate-limited via the AnonCart policy
• Cart Id is hidden from API responses; use Guid for all client-side operations
• POST /api/v1/Cart with UserGuid requires a valid JWT — the controller returns 401 if UserGuid is provided but no token is present
• Convert and preview use the same price resolution logic — preview is a dry run of convert
• Address snapshots are point-in-time copies; they do not link back to a live address record
• All data is tenant-scoped
• Internal errors are logged but not exposed to API consumers