BETA

Staged Quotes

Staged Quotes are used by a Seller to prepare Quotes for a Buyer.

Representations

StagedQuote

id
String

The unique ID of the StagedQuote.

version
Int

Current version of the StagedQuote.

key
String

User-specific unique identifier of the staged quote.

stagedQuoteState

Predefined states tracking the status of the Staged Quote.

customer

The Buyer who requested the quote.

quoteRequest

The Quote Request related to this Staged Quote.

quotationCart

The Cart containing the offered items.

validTo

Expiration date for the quote.

sellerComment
String

The text message included in the offer from the Seller.

state

State of this Staged Quote. This reference can point to a State in a custom workflow.

custom

Custom Fields of this Staged Quote.

createdAt

Date and time (UTC) the StagedQuote was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the StagedQuote was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

StagedQuoteDraft

key
String

User-defined unique identifier for the StagedQuote.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
quoteRequest

The QuoteRequest from which this StagedQuote is created.

quoteRequestVersion
Int

Current version of the QuoteRequest.

state

State of this Staged Quote. This reference can point to a State in a custom workflow.

custom

Custom Fields to be added to the StagedQuote.

  • If specified, the Custom Fields are merged with the Custom Fields on the referenced QuoteRequest and added to the StagedQuote.
  • If empty, the Custom Fields on the referenced QuoteRequest are added to the StagedQuote automatically.

StagedQuotePagedQueryResponse

PagedQueryResult with results containing an array of StagedQuote.

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of StagedQuote

Staged Quotes matching the query.

StagedQuoteReference

id
String

Unique ID of the referenced resource.

typeId
String
"staged-quote"

References a StagedQuote.

obj

Contains the representation of the expanded StagedQuote. Only present in responses to requests with Reference Expansion for StagedQuote.

StagedQuoteResourceIdentifier

id
String

Unique identifier of the referenced resource. Required if key is absent.

key
String

User-defined unique identifier of the referenced resource. Required if id is absent.

typeId
String
"staged-quote"

References a StagedQuote.

StagedQuoteState

Predefined states tracking the status of the Staged Quote.

InProgress

Initial state after creating the StagedQuote indicating the Seller is preparing the Quote.

Sent

A state indicating the StagedQuote has been sent to the Buyer.

Closed

A state indicating the StagedQuote flow was finished.

Get StagedQuote

Get StagedQuote by ID

GET
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id}
OAuth 2.0 Scopes:
view_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StagedQuote.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200StagedQuote

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Get StagedQuote by Key

GET
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key}
OAuth 2.0 Scopes:
view_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StagedQuote.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200StagedQuote

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Query StagedQuote

GET
https://api.{region}.commercetools.com/{projectKey}/staged-quotes
OAuth 2.0 Scopes:
view_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:

200StagedQuotePagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/staged-quotes -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: StagedQuotePagedQueryResponsejson
{
"limit" : 20,
"offset" : 0,
"count" : 2,
"total" : 2,
"results" : [ {
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}, {
"id" : "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "768e5783-73c8-3f2d-22f4-3c90b872c700"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "2v3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "82f2a767-bf19-47ab-982c-6720a03a3912"
},
"stagedQuoteState" : "Sent"
} ]
}

Create StagedQuote

POST
https://api.{region}.commercetools.com/{projectKey}/staged-quotes
OAuth 2.0 Scopes:
manage_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:StagedQuoteDraft
Response:

201StagedQuote

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/staged-quotes -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "168e5783-73c8-4f2d-91f4-3c90b872c708"
},
"quoteRequestVersion" : 1
}
DATA
201 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Update StagedQuote

Update StagedQuote by ID

POST
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id}
OAuth 2.0 Scopes:
manage_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StagedQuote.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int
actions
Response:

200StagedQuote

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeStagedQuoteState",
"stagedQuoteState" : "Sent"
} ]
}
DATA
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Update StagedQuote by Key

POST
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key}
OAuth 2.0 Scopes:
manage_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StagedQuote.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int
actions
Response:

200StagedQuote

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeStagedQuoteState",
"stagedQuoteState" : "Sent"
} ]
}
DATA
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Update actions

Change Staged Quote State

action
String
"changeStagedQuoteState"
stagedQuoteState

The new quote staged state to be set for the Quote Staged.

Example: json
{
"action" : "changeStagedQuoteState",
"stagedQuoteState" : "Sent"
}

Set Seller Comment

action
String
"setSellerComment"
sellerComment
String

If sellerComment is absent or null, this field will be removed if it exists.

Example: json
{
"action" : "setSellerComment",
"sellerComment" : "Please let me know if this matches your expectations"
}

Set Valid To

action
String
"setValidTo"
validTo

If validTo is absent or null, this field will be removed if it exists.

Example: json
{
"action" : "setValidTo",
"validTo" : "2022-09-22T15:41:55.816Z"
}

Set Custom Type

action
String
"setCustomType"
type

Defines the Type that extends the StagedQuote with Custom Fields. If absent, any existing Type and Custom Fields are removed from the StagedQuote.

fields

Sets the Custom Fields fields for the StagedQuote.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "TextString"
}
}

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

Transition State

If the existing State has set transitions, there must be a direct transition to the new State. If transitions is not set, no validation is performed. This update action produces the Staged Quote State Transition Message.

action
String
"transitionState"
state

Value to set. If there is no State yet, the new State must be an initial State.

force
Boolean

Switch validations on or off.

Default: false
Example: json
{
"action" : "transitionState",
"state" : {
"typeId" : "state",
"id" : "{{state-id}}"
}
}

Delete StagedQuote

Delete StagedQuote by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id}
OAuth 2.0 Scopes:
manage_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StagedQuote.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:

200StagedQuote

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}

Delete StagedQuote by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key}
OAuth 2.0 Scopes:
manage_staged_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StagedQuote.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:

200StagedQuote

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: StagedQuotejson
{
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 1,
"createdAt" : "2022-09-22T15:36:17.510Z",
"lastModifiedAt" : "2022-09-22T15:41:55.816Z",
"quotationCart" : {
"typeId" : "cart",
"id" : "1a3faa00-55fa-4ab8-bee7-933c31e18dcc"
},
"quoteRequest" : {
"typeId" : "quote-request",
"id" : "8a3faa00-33fa-4ab8-bee7-833f31e18dcc"
},
"customer" : {
"typeId" : "customer",
"id" : "92f5a867-bf19-47ab-982c-6720a03a3921"
},
"stagedQuoteState" : "InProgress"
}