# Quote Requests and Staged Quotes

Negotiation in this flow starts with two resources: the buyer's [Quote Request](/api/projects/quote-requests.md) and the seller's [Staged Quote](/api/projects/staged-quotes.md). 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.

```http
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](/learning-model-b2b-commerce/configure-associate-access/associate-roles-and-permissions.md).

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](/urn?urn=ctp%3Aapi%3Atype%3AQuoteRequestState). 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](/urn?urn=ctp%3Aapi%3Atype%3AStagedQuoteState) 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.

| Mechanism | How it applies | Fits |
| --- | --- | --- |
| [DirectDiscount](/urn?urn=ctp%3Aapi%3Atype%3ADirectDiscount) | The seller sets a discount on the whole `quotationCart` or specific Line Items, with no code and no eligibility predicate | A one-off negotiated reduction agreed for this deal |
| Discount Code / Cart Discount | A reusable, rule-based discount the buyer or system applies | Broad campaigns and standing promotions, not bespoke negotiation |

```http
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.

## Related pages

- [Area overview page with navigation](/learning-model-b2b-commerce.md)
- [Previous page: The Quote lifecycle](/learning-model-b2b-commerce/implement-b2b-purchase-flows/the-quote-lifecycle.md)
- [Next page: Quotes, price locking, and renegotiation](/learning-model-b2b-commerce/implement-b2b-purchase-flows/quotes-price-locking-and-renegotiation.md)