Cart Service

Back

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.

Behavior:

• An empty Items list deletes the entire cart
• Quantity <= 0 removes that item from the cart

Response:

• 200 OK — CartModel

Authorization:

• [AllowAnonymous] — no token required

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 — no data is written

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 (sales order). 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
• 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
• IsBillingSameAsShipping (bool) — if true, billing snapshot is copied from shipping

Behavior:

• Creates a Document and DocumentLine records from cart contents
• 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
• Source cart is deleted on success

Response:

• 201 Created — DocumentModel (fully populated, same shape as /api/v1/Documents/{id})

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

Note: Id is present in the DB but omitted from JSON responses.

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)

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:

• BillingAddressSnapshots (type: DocumentBillingAddressSnapshotModel?) — billing address snapshot
• ShippingAddressSnapshots (type: DocumentShippingAddressSnapshotModel) — shipping address snapshot
• Notes (type: string?) — order notes
• PurchaseOrderRef (type: string?) — customer PO reference
• IsBillingSameAsShipping (type: bool) — copy billing from shipping

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