Documentation

Standalone Prices

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

The Standalone Prices API 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:

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. When priceMode is not set, the API treats the Product as having the Embedded ProductPriceMode.

Information icon

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 API uses for LineItem Price selection and Product Price selection.

Graduation cap iconLearn more about Standalone Prices in our self-paced Pricing setup module.

Representations

StandalonePrice

id​
String​

Unique identifier of the StandalonePrice.

version​
Int​

Current version of the StandalonePrice.

key​
String​

User-defined unique identifier of the StandalonePrice.

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

SKU of the ProductVariant to which this Price is associated.

value​
TypedMoney​

Money value of this Price.

country​
CountryCode​

Country for which this Price is valid.

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

CustomerGroup for which this Price is valid.

channel​
ChannelReference​

Product distribution Channel for which this Price is valid.

validFrom​
DateTime​

Date from which the Price is valid.

validUntil​
DateTime​

Date until the Price is valid. Standalone Prices that are no longer valid are not automatically deleted, but they can be deleted if necessary.

tiers​
Array of PriceTier​

Price tiers if any are defined.

discounted​
DiscountedPrice​

Set if a matching ProductDiscount exists. If set, the API 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 roundingExternal link icon.

staged​BETA
StagedStandalonePrice​

Staged changes of the StandalonePrice. Only present if the StandalonePrice has staged changes.

active​BETA
Boolean​

If set to true, the StandalonePrice is considered during price selection. If set to false, the StandalonePrice is not considered during price selection.

Default: true​
custom​
CustomFields​

Custom Fields for the StandalonePrice.

createdAt​
DateTime​

Date and time (UTC) the StandalonePrice 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 StandalonePrice was last updated.

lastModifiedBy​BETA
LastModifiedBy​

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

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 for an SKU which has a Standalone Price with exactly the same price scope, or with overlapping validity periods within the same price scope returns the DuplicateStandalonePriceScope and OverlappingStandalonePriceValidity errors, respectively. 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: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
sku​
String​

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

value​
Money​

Sets the money value of this Price.

country​
CountryCode​

Sets the country for which this Price is valid.

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

Sets the CustomerGroup for which this Price is valid.

channel​
ChannelResourceIdentifier​

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

validFrom​
DateTime​

Sets the date from which the Price is valid. Must be at least 1 ms earlier than validUntil.

validUntil​
DateTime​

Sets the date until the Price is valid. Must be at least 1 ms later than validFrom. Standalone Prices that are no longer valid are not automatically deleted, but they can be deleted if necessary.

tiers​
Array of PriceTierDraft​

Sets price tiers.

discounted​
DiscountedPriceDraft​

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

active​BETA
Boolean​

If set to true, the StandalonePrice is considered during price selection. If set to false, the StandalonePrice is not considered during price selection.

Default: true​
custom​
CustomFieldsDraft​

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

Reference to a StandalonePrice.

id​
String​

Unique ID of the referenced resource.

typeId​
String​
"standalone-price"

References a StandalonePrice.

obj​
StandalonePrice​

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

StandalonePriceResourceIdentifier

ResourceIdentifier to a StandalonePrice.

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​
"standalone-price"

References a StandalonePrice.

StagedStandalonePrice BETA

Staged changes on a Standalone Price. To update the value property of a Staged Standalone Price, use the corresponding update action. To apply all staged changes to the Standalone Price, use the applyStagedChanges update action.

value​
TypedMoney​

Money value of the StagedStandalonePrice.

discounted​
DiscountedPrice​

Discounted price for the StagedStandalonePrice.

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200StandalonePrice
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200StandalonePrice
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

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
​
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:
200StandalonePricePagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/standalone-prices -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: StandalonePricePagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 2,
  "total" : 2,
  "results" : [ {
    "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
    "version" : 1,
    "sku" : "PT974SKT",
    "value" : {
      "type" : "centPrecision",
      "currencyCode" : "EUR",
      "centAmount" : 10000,
      "fractionDigits" : 2
    },
    "active" : true,
    "createdAt" : "2022-05-09T08:29:13.253Z",
    "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
  }, {
    "id" : "9d73608c-88ea-11ec-a8a3-0242ac120002",
    "version" : 1,
    "key" : "random-key-12345",
    "sku" : "PT562ZTB",
    "value" : {
      "type" : "centPrecision",
      "currencyCode" : "USD",
      "centAmount" : 15000,
      "fractionDigits" : 2
    },
    "country" : "DE",
    "channel" : {
      "typeId" : "channel",
      "id" : "2ae21284-88ea-11ec-a8a3-0242ac120002"
    },
    "customerGroup" : {
      "typeId" : "customer-group",
      "id" : "15a1678a-88ea-11ec-a8a3-0242ac120002"
    },
    "active" : true,
    "createdAt" : "2022-05-09T09:29:13.253Z",
    "lastModifiedAt" : "2022-05-09T10:36:55.401Z"
  } ]
}
Clipboard icon

Create StandalonePrice

POST
https://api.{region}.commercetools.com/{projectKey}/standalone-prices

Produces the StandalonePriceCreated Message.

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:StandalonePriceDraftasapplication/json
Response:
201StandalonePriceasapplication/json
Request Example:cURL
curl 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
Clipboard icon
201 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
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 ConcurrentModification error is returned.

actions​
Array of StandalonePriceUpdateAction​

Update actions to be performed on the StandalonePrice.

Response:
200StandalonePriceasapplication/json
Request Example:cURL
curl 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
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
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 ConcurrentModification error is returned.

actions​
Array of StandalonePriceUpdateAction​

Update actions to be performed on the StandalonePrice.

Response:
200StandalonePriceasapplication/json
Request Example:cURL
curl 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
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

Update actions

Change Value

Updating the value of a StandalonePrice produces the StandalonePriceValueChangedMessage.

action​
String​
"changeValue"
value​
Money​

New value to set. Must not be empty.

staged​BETA
Boolean​

If set to true the update action applies to the StagedStandalonePrice. If set to false, the update action applies to the current StandalonePrice.

Default: false​
Example: json
{
  "action" : "changeValue",
  "staged" : false,
  "value" : {
    "currencyCode" : "EUR",
    "centAmount" : 10000
  }
}
Clipboard icon

Change Active BETA

Updating the value of a StandalonePrice produces the StandalonePriceActiveChangedMessage.

action​
String​
"changeActive"
active​
Boolean​

New value to set for the active field of the StandalonePrice.

Example: json
{
  "action" : "changeActive",
  "active" : false
}
Clipboard icon

Set Key

Sets the key on a Standalone Price. Produces the StandalonePriceKeySet Message.

action​
String​
"setKey"
key​
String​

Value to set. Must be unique. If empty, any existing value will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action" : "setKey",
  "key" : "new-key"
}
Clipboard icon

Set Custom Type

action​
String​
"setCustomType"
type​
TypeResourceIdentifier​

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

fields​
FieldContainer​

Sets the Custom Fields fields for the StandalonePrice.

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

Set Custom Field

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

Set Discounted Price

Discounts a Standalone Price. The referenced ProductDiscount in the discounted field must be of type external, active, and its predicate must match the referenced Price. Produces the StandalonePriceExternalDiscountSet Message.

action​
String​
"setDiscountedPrice"
discounted​
DiscountedPriceDraft​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setDiscountedPrice",
  "discounted" : {
    "value" : {
      "type" : "centPrecision",
      "currencyCode" : "EUR",
      "centAmount" : 2990,
      "fractionDigits" : 2
    },
    "discount" : {
      "typeId" : "product-discount",
      "id" : "{{product-discount-id}}"
    }
  }
}
Clipboard icon

Apply Staged Changes BETA

Applies all staged changes to the StandalonePrice by overwriting all current values with the values in the StagedStandalonePrice. After successfully applied, the StagedStandalonePrice will be removed from the StandalonePrice. An applyStagedChanges update action on a StandalonePrice that does not contain any staged changes will return a 400 Bad Request error. Applying staged changes successfully will produce the StandalonePriceStagedChangesApplied Message.

action​
String​
"applyStagedChanges"
Example: json
{
  "action" : "applyStagedChanges"
}
Clipboard icon

Delete StandalonePrice

Delete StandalonePrice by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/{id}

Produces the StandalonePriceDeleted Message.

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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
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}'
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon

Delete StandalonePrice by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/standalone-prices/key={key}

Produces the StandalonePriceDeleted Message.

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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
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}'
Clipboard icon
200 Response Example: StandalonePricejson
{
  "id" : "3f8812c6-88e8-11ec-a8a3-0242ac120002",
  "version" : 1,
  "sku" : "PT974SKT",
  "value" : {
    "type" : "centPrecision",
    "currencyCode" : "EUR",
    "centAmount" : 10000,
    "fractionDigits" : 2
  },
  "active" : true,
  "createdAt" : "2022-05-09T08:29:13.253Z",
  "lastModifiedAt" : "2022-05-09T12:36:55.401Z"
}
Clipboard icon