Learning PathModule

Quote Requests and Staged Quotes

Follow the first half of the Quote flow, where the buyer requests terms and the seller prepares a counter-offer on a working copy.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Describe how a Quote Request is created from a Cart and the states it moves through.

  • Explain how a Staged Quote gives the seller a working copy to negotiate on.

  • Distinguish a DirectDiscount from a Discount Code when the seller adjusts a Staged Quote.

Negotiation in this flow starts with two resources: the buyer's Quote Request and the seller's Staged Quote. The Quote Request captures what the buyer is asking for; the Staged Quote is where the seller reshapes the offer before it becomes binding.

The Quote Request: the buyer's ask

The buyer creates a Quote Request from a Cart, carrying the Cart's Line Items and Business Unit context. The buyer can attach a comment describing what they want, for example a target price or a delivery wish.

POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/quote-requests HTTP/1.1
Content-Type: application/json

{
  "cart": { "typeId": "cart", "id": "{cartId}" },
  "cartVersion": 8,
  "comment": "Requesting volume pricing for 500 units, delivery split across Q2."
}
Creating a Quote Request requires the buyer's role to include a permission such as CreateMyQuoteRequestsFromMyCarts, consistent with the separation of duties you designed in Configure associate access.

Before you design the buyer's Cart, check whether the Cart can be used for a Quote Request:

  • The Cart must have shippingMode: Single and a shippingAddress.
  • The Cart cannot be anonymous.
  • The Cart cannot have Discount Codes.

For negotiated delivery to multiple sites, create separate single-shipping Quote Requests per destination, or negotiate the commercial terms first and then use the multi-shipping Direct Order pattern from the previous page.

After the Quote Request is created, it moves through these states:

The full state list lives in QuoteRequestState. For design decisions, focus on whether a Submitted request is accepted by the seller and moves toward a Staged Quote, or leaves the negotiation path because the seller rejects it, the buyer cancels it, or the request is closed.

The Staged Quote: the seller's working copy

When the seller accepts a Quote Request, they create a Staged Quote. Its central feature is the quotationCart: a working copy of the basket that the seller can edit without touching the buyer's original Cart. On the quotationCart, the seller can add or remove Line Items, change quantities, and apply the negotiated discount.
A Staged Quote is prepared while it is InProgress, sent to the buyer when the seller is ready, and closed when the Staged Quote flow is finished. See StagedQuoteState for the canonical state values.

DirectDiscount versus Discount Code

How the seller applies the negotiated reduction matters, because B2B negotiation is deliberate, not promotional. The seller has two mechanisms on the quotationCart, and they are not interchangeable.
MechanismHow it appliesFits
DirectDiscountThe seller sets a discount on the whole quotationCart or specific Line Items, with no code and no eligibility predicateA one-off negotiated reduction agreed for this deal
Discount Code / Cart DiscountA reusable, rule-based discount the buyer or system appliesBroad campaigns and standing promotions, not bespoke negotiation
POST /{projectKey}/staged-quotes/{stagedQuoteId} HTTP/1.1
Content-Type: application/json

{
  "version": 2,
  "actions": [
    {
      "action": "changeStagedQuoteState",
      "stagedQuoteState": "Sent"
    }
  ]
}

A DirectDiscount is the natural fit for a quote, because the agreed reduction belongs to this one negotiation and should not be reusable elsewhere. A Cart cannot mix the two models: a basket that has direct discounts cannot also carry discount codes.

Key takeaways

  • The buyer creates a Quote Request from a supported Cart, optionally with a comment, governed by a permission such as CreateMyQuoteRequestsFromMyCarts.
  • The source Cart must use shippingMode: Single, have a shippingAddress, not be anonymous, and not contain Discount Codes.
  • Quote Request states are Submitted, Accepted, Rejected, Cancelled, and Closed.
  • The seller accepts the request and works on a Staged Quote's quotationCart, a separate copy, leaving the buyer's Cart intact.
  • Staged Quote states are InProgress, Sent, and Closed.
  • The seller uses a DirectDiscount for a one-off negotiated reduction, not a Discount Code, which is for reusable promotions.

Test your knowledge