Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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​
StagedQuoteState​

Predefined states tracking the status of the Staged Quote.

customer​
CustomerReference​

The Buyer who requested the Quote.

quoteRequest​
QuoteRequestReference​

Quote Request related to the Staged Quote.

quotationCart​
CartReference​

Cart containing the offered items. May contain either DirectDiscounts or CartDiscounts.

validTo​
DateTime​

Expiration date for the Quote.

sellerComment​
String​

Message from the Seller included in the offer.

state​
StateReference​

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

purchaseOrderNumber​
String​

The Purchase Order Number is typically set by the Buyer on a QuoteRequest to track the purchase order during the quote and order flow.

businessUnit​
BusinessUnitKeyReference​

The BusinessUnit for the Staged Quote.

custom​
CustomFields​

Custom Fields of the Staged Quote.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

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

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

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

StagedQuoteDraft

key​
String​

User-defined unique identifier for the StagedQuote.

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

QuoteRequest from which the StagedQuote is created.

quoteRequestVersion​
Int​

Current version of the QuoteRequest.

quoteRequestStateToAccepted​
Boolean​

If true, the quoteRequestState of the referenced QuoteRequest will be set to Accepted.

Default: false​
state​
StateReference​

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

custom​
CustomFieldsDraft​

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

Reference to a StagedQuote.

id​
String​

Unique ID of the referenced resource.

typeId​
String​
"staged-quote"

References a StagedQuote.

obj​
StagedQuote​

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

StagedQuoteResourceIdentifier

ResourceIdentifier to a StagedQuote.

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 that the Seller is preparing the Quote.

Sent

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

Closed

A state indicating that 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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200StagedQuoteasapplication/json
Request Example:cURL
curl --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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200StagedQuoteasapplication/json
Request Example:cURL
curl --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 StagedQuotes

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
​
QueryPredicate
​
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
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

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:
200StagedQuotePagedQueryResponseasapplication/json
Request Example:cURL
curl --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"
    }
  ]
}

Check if StagedQuote exists

Check if StagedQuote exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id}

Checks if a StagedQuote exists for a given id. Returns a 200 OK status if the StagedQuote exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/staged-quotes/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if StagedQuote exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key}

Checks if a StagedQuote exists for a given key. Returns a 200 OK status if the StagedQuote exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/staged-quotes/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if StagedQuote exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/staged-quotes

Checks if a StagedQuote exists for a given Query Predicate. Returns a 200 OK status if any StagedQuotes match the Query Predicate or a 404 Not Found otherwise.

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
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/staged-quotes -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:StagedQuoteDraftasapplication/json
Response:
201StagedQuoteasapplication/json
Request Example:cURL
curl 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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the StagedQuote to which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions​
Array of StagedQuoteUpdateAction​

Update actions to be performed on the StagedQuote.

Response:
200StagedQuoteasapplication/json
Request Example:cURL
curl 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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the StagedQuote to which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions​
Array of StagedQuoteUpdateAction​

Update actions to be performed on the StagedQuote.

Response:
200StagedQuoteasapplication/json
Request Example:cURL
curl 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​
StagedQuoteState​

New state to be set for the Staged Quote.

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​
DateTime​

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​
TypeResourceIdentifier​

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

fields​
FieldContainer​

Sets the Custom Fields fields for the StagedQuote.

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

Set CustomField

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

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

Example: json
{
  "action": "setCustomField",
  "name": "ExampleStringTypeField",
  "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​
StateResourceIdentifier​

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
​
Expansion
​
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:
200StagedQuoteasapplication/json
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
​
Expansion
​
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:
200StagedQuoteasapplication/json
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"
}