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

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
• 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)

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?, optional) — target document type code (e.g. "SALES_ORDER", "QUOTE"). Determines document type and initial status; defaults to SALES_ORDER behaviour if omitted
• 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 (currently dormant) warning-acknowledgement gate.
• 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})
• 422 Unprocessable Entity — CartHasNoConvertibleItems if nothing in the cart is convertible
• 409 Conflict — CartContainsExcludedItems if strict conversion encounters invalid items

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

ConvertCartRequest

Extends PreviewCartRequest. Additional fields:

• DocumentTypeGuid (type: string?) — target document type code (e.g. "SALES_ORDER", "QUOTE"). Determines the document type and initial status on conversion
• 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

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