BETA

Standalone Prices

A Standalone Price assigns a Price to a Product Variant for a given scope.

The Standalone Prices feature provides an alternative way to store your product prices as standalone resources. In comparison to Prices embedded inside the Product, this approach allows going beyond the limit of 100 prices per ProductVariant. It also brings a more flexible way to query and manage your Prices, separately from your Products, which contributes to better query performance.

The differences between the two approaches are explained below:

  • StandalonePrices are managed and queried through the StandalonePrices API and associated to a ProductVariant through the sku field. Through the API endpoint you can create, update and delete prices, as well as query or fetch them by ID or by Key. It enables to store up to 50 000 Prices per ProductVariant.

  • EmbeddedPrices are located inside the prices field of the ProductVariant to which they are associated, therefore they are managed and queried through the Product API endpoint. You can add prices when creating a Product or manage the prices of an existing Product using the update actions addPrice, setPrices, changePrice and removePrice. It has a limit of 100 prices per ProductVariant.

To specify where the Prices of a particular Product are located, you need to set the ProductPriceMode accordingly. You can set the priceMode field on the ProductDraft when creating a Product or afterwards by the Set PriceMode update action. If priceMode is not set, the Platform applies the Embedded ProductPriceMode by default.

A Product can have embedded Prices as well as Standalone Prices at the same time, but the priceMode on a Product determines which Price the Platform uses for LineItem Price selection and Product Price Selection.

Representations

StandalonePrice

id
String

Platform-generated unique identifier of the StandalonePrice.

version
Int

Current version of the StandalonePrice.

key
String

User-defined unique identifier of the StandalonePrice.

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

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

sku
String

SKU of the ProductVariant to which this Price is associated.

value

Money value of this Price.

country

Country for which this Price is valid.

Pattern: ^[A-Z]{2}$
customerGroup

CustomerGroup for which this Price is valid.

channel

Product distribution Channel for which this Price is valid.

validFrom

Date from which the Price is valid.

validUntil

Date until the Price is valid.

tiers
Array of PriceTier

Price tiers if any are defined.

discounted

Set if a matching ProductDiscount exists. If set, the Platform uses the discounted value for the LineItem Price selection. When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.

custom

Custom Fields for the StandalonePrice.

StandalonePriceDraft

Standalone Prices are defined with a scope consisting of currency and optionally country, customerGroup, and channel and/or a validity period (validFrom and/or validTo). For more information see price selection. Creating a Standalone Price is rejected if there already exists a Standalone Price for the same SKU with exactly the same price scope, or with overlapping validity periods within the same price scope. A Price without validity period does not conflict with a Price defined for a time period.

key
String

User-defined unique identifier for the StandalonePrice.

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

Specifies to which ProductVariant the Platform associates this Price. It is not validated to exist in product variants.

value

Sets the money value of this Price.

country

Sets the country for which this Price is valid.

Pattern: ^[A-Z]{2}$
customerGroup

Sets the CustomerGroup for which this Price is valid.

channel

Sets the product distribution Channel for which this Price is valid.

validFrom

Sets the date from which the Price is valid.

validUntil

Sets the date until the Price is valid.

tiers
Array of PriceTierDraft

Sets price tiers.

discounted

Sets a discounted price for this Price that is different from the base price with value.

custom

Custom Fields for the StandalonePrice.

StandalonePricePagedQueryResponse

limit
Int

Number of requested results.

offset
Int

Offset supplied by the client or server default. It is the number of elements skipped, not a page number.

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 StandalonePrice

StandalonePrices matching the query.

StandalonePriceReference

id
String

Unique ID of the referenced resource.

typeId
String
"standalone-price"

Type of referenced resource.

obj

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

StandalonePriceResourceIdentifier

id
String

Platform-generated 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
"standalone-price"

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

Get StandalonePrice

Get StandalonePrice by ID

GET
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id}
OAuth 2.0 Scopes:
view_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StandalonePrice.

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

200StandalonePrice

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get StandalonePrice by Key

GET
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key}
OAuth 2.0 Scopes:
view_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StandalonePrice.

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

200StandalonePrice

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query StandalonePrices

GET
https://api.{region}.commercetools.com/{projectKey}/standalone-prices
OAuth 2.0 Scopes:
view_standalone_prices:{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:

200StandalonePricePagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/standalone-prices -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create StandalonePrice

POST
https://api.{region}.commercetools.com/{projectKey}/standalone-prices
OAuth 2.0 Scopes:
manage_standalone_prices:{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.
Response:

201StandalonePrice

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/standalone-prices -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"sku" : "PT974SKT",
"value" : {
"currencyCode" : "EUR",
"centAmount" : 10000
}
}
DATA

Update StandalonePrice

Update StandalonePrice by ID

POST
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id}
OAuth 2.0 Scopes:
manage_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StandalonePrice.

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

Expected version of the StandalonePrice on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict error will be returned.

actions

Update actions to be performed on the StandalonePrice.

Response:

200StandalonePrice

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"currencyCode" : "EUR",
"centAmount" : 10000
}
} ]
}
DATA

Update StandalonePrice by Key

POST
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key}
OAuth 2.0 Scopes:
manage_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StandalonePrice.

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

Expected version of the StandalonePrice on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict error will be returned.

actions

Update actions to be performed on the StandalonePrice.

Response:

200StandalonePrice

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeValue",
"value" : {
"currencyCode" : "EUR",
"centAmount" : 10000
}
} ]
}
DATA

Update actions

Change Value

action
String
"changeValue"
value

New value to set. Must not be empty.

Example: json
{
"action" : "changeValue",
"value" : {
"currencyCode" : "EUR",
"centAmount" : 10000
}
}

Set Custom Type

action
String
"setCustomType"
type

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

fields

Sets the Custom Fields fields for the StandalonePrice.

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

Set Custom Field

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"
}

Delete StandalonePrice

Delete StandalonePrice by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id}
OAuth 2.0 Scopes:
manage_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the StandalonePrice.

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

Last seen version of the resource.

Response:

200StandalonePrice

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Delete StandalonePrice by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key}
OAuth 2.0 Scopes:
manage_standalone_prices:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the StandalonePrice.

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

Last seen version of the resource.

Response:

200StandalonePrice

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2022 commercetools
Privacy PolicyImprint