Guides
Start typing to search…

Buyer Experience

This page describes how a Customer User discovers, inspects, and uses Operations from the shop. It focuses on the end to end flow and what to expect in terms of visibility, quantities, and validations.

Keep in mind

  • Buyers see only ACTIVE Operations that match dates and store scope, and for PRIVATE type only if their Account is attached.
  • Inside an Operation, buyers see only lines allowed by Catalog Views.
  • Starting from an Operation creates an order with default quantities per line; standard stock and pack rules apply in addition to Operation min max.
  • Multiple orders can be initiated from the same Operation for the same Account.

📋 Listing Operations

Route GET /shop/operations Returns Operations that are ACTIVE and within the current date window. For PRIVATE, only Operations where the current Account is attached are returned.

What buyers see

  • Title and description in the current locale.
  • Dates and status.
  • Operation type PUBLIC or PRIVATE.

🔎 Viewing details and lines

Routes

  • GET /shop/operations/{id}
  • GET /shop/operations/{id}/lines

Rules

  • Only ACTIVE Operations are returned; otherwise 404.
  • Lines follow Catalog View visibility for the Account.
  • Prices follow the precedence Operation → Account → Tag → Public.

▶️ Starting an order

Routes

  • Order POST /operations/{operationId}/order

Behavior

  • The created object is linked to the Operation; multi origin is supported.
  • Default quantity per visible line
    1. recommendedQuantity if present and valid
    2. else minQuantity if present and greater than 0
    3. else 1
  • Validations on add apply as usual
    • Stock availability and pack multiples
    • Operation min max bounds per line

Scope

  • You can start a full order including all visible lines or a partial one using a selection of product variant ids.

✏️ Editing after start

  • Buyers can increase or decrease quantities within Min Max and pack rules.
  • If Min = 0 for a line, it may be removed.
  • Buyers may add other products not part of the Operation; standard rules apply.
  • If the Operation later becomes INACTIVE, follow normal lifecycle behavior for existing carts orders in your storefront.

🔁 Multiple initiations

  • A Customer User can initiate several orders from the same Operation for the same Account.
  • Each object keeps a link to the Operation for tracking and reporting.

🧭 Buyer flow at a glance

The following diagram shows the typical buyer journey from list to cart order creation.

sequenceDiagram
    participant Buyer
    participant ShopAPI as Shop API

    Buyer->>ShopAPI: GET /shop/operations
    ShopAPI-->>Buyer: ACTIVE operations within dates and scope

    Buyer->>ShopAPI: GET /shop/operations/{id}
    ShopAPI-->>Buyer: Operation details
    Buyer->>ShopAPI: GET /shop/operations/{id}/lines
    ShopAPI-->>Buyer: Visible lines only

    alt Start order
        Buyer->>ShopAPI: POST /operations/{operationId}/order
        ShopAPI-->>Buyer: Order created with default quantities
    end

🧩 Examples

Example — Full order from an Operation

  • The Operation contains 50 lines. Catalog Views expose 40 lines for this Account.
  • Starting an order initializes those 40 lines using the default quantity rule. The 10 hidden lines are not included.

Example — Partial order with selection

  • The buyer selects 12 specific product variants from the Operation and starts an order.
  • Only those 12 appear in the order, with default quantities applied per line.

🔗 API quicklinks

Required headers (Shop)

  • dj-client: ACCOUNT
  • dj-api-key: your key
  • dj-store, dj-store-view: used for store scoping
  • locale (optional): used for localized front DTOs

🔜 Shop — discover & read

  • GET /shop/operations
    • Returns Operations visible to the current Account: status=ACTIVE, now within [startDate, endDate], and store matches; for PRIVATE, the Account must be attached.
  • GET /shop/operations/(id)
    • Returns details for a single Operation if eligible (same rules as above).
    • 404 when not ACTIVE, out of date window, wrong store, or not eligible (e.g., PRIVATE without attachment).
  • GET /shop/operations/(id)/lines
    • Returns visible product lines only. Product visibility inside an Operation follows the same Catalog Views rules as outside Operations.
    • Pricing precedence (when multiple offers exist): Operation → Account → Tag → Public.

🔜 Start from an Operation (Checkout)

  • POST /operations/(operationId)/order — Start an order (Checkout v3) from this Operation.

Behavior on start:

  • Each visible line is initialized with a default quantity: recommended, else min, else 1.
  • Standard stock and pack multiple validations apply, plus Operation min/max constraints.
  • Full vs partial initiation (selected product variants) depends on your Checkout API payload

Updated 17 days ago