The Client class

class commercetools.Client(*args, **kwargs)

Bases: commercetools.base_client.BaseClient, commercetools.services.ServicesMixin

Note

The classes listed below should generally not be instantiated directly but instead be accessed via the commercetools.Client() class.

Client.carts

class commercetools.services.carts.CartService(client)

Bases: commercetools.services.abstract.AbstractService

A shopping cart holds product variants and can be ordered.

create(draft, *, expand=None)

Creating a cart can fail with an InvalidOperation if the referenced shipping method in the

CartDraft has a predicate which does not match the cart. A shopping cart holds product variants and can be ordered.

Return type:Cart

delete_by_id(id, version, *, expand=None, data_erasure=None, force_delete=False)

Return type:Cart

get_by_customer_id(customer_id, *, expand=None)

Retrieves the active cart of the customer that has been modified most recently.

It does not consider carts with CartOrigin Merchant. If no active cart exists, a 404 Not Found error is returned. The cart may not contain up- to-date prices, discounts etc. If you want to ensure they’re up-to-date, send an Update request with the Recalculate update action instead.

Return type:Cart

get_by_id(id, *, expand=None)

The cart may not contain up-to-date prices, discounts etc.

If you want to ensure they’re up-to-date, send an Update request with the Recalculate update action instead.

Return type:Cart

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None, customer_id=None)

A shopping cart holds product variants and can be ordered.

Return type:CartPagedQueryResponse

replicate(draft)

Return type:Cart

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:Cart

Client.categories

class commercetools.services.categories.CategoryService(client)

Bases: commercetools.services.abstract.AbstractService

Categories are used to organize products in a hierarchical structure.

create(draft, *, expand=None)

Creating a category produces the CategoryCreated message.

Categories are used to organize products in a hierarchical structure.

Return type:Category

delete_by_id(id, version, *, expand=None, force_delete=False)

Return type:Category

delete_by_key(key, version, *, expand=None, force_delete=False)

Return type:Category

get_by_id(id, *, expand=None)

Return type:Category

get_by_key(key, *, expand=None)

Return type:Category

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

Categories are used to organize products in a hierarchical structure.

Return type:CategoryPagedQueryResponse

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:Category

update_by_key(key, version, actions, *, expand=None, force_update=False)

Return type:Category

Client.channels

class commercetools.services.channels.ChannelService(client)

Bases: commercetools.services.abstract.AbstractService

Channels represent a source or destination of different entities.

They can be used to model warehouses or stores.

create(draft, *, expand=None)

Channels represent a source or destination of different entities. They can be used to model warehouses or stores.

Return type:Channel

delete_by_id(id, version, *, expand=None, force_delete=False)

Return type:Channel

get_by_id(id, *, expand=None)

Return type:Channel

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

Channels represent a source or destination of different entities. They can be used to model warehouses or stores.

Return type:ChannelPagedQueryResponse

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:Channel

Client.custom_objects

class commercetools.services.custom_objects.CustomObjectService(client)

Bases: commercetools.services.abstract.AbstractService

Store custom JSON values.

create(draft, *, expand=None)

Creates a new custom object or updates an existing custom object.

If an object with the given container/key exists, the object will be replaced with the new value and the version is incremented. If the request contains a version and an object with the given container/key exists then the version must match the version of the existing object. Concurrent updates for the same custom object still can result in a Conflict (409) even if the version is not provided. Fields with null values will not be saved. Store custom JSON values.

Return type:CustomObject

create_or_update(draft, *, expand=None)

Creates a new custom object or updates an existing custom object.

If an object with the given container/key exists, the object will be replaced with the new value and the version is incremented. If the request contains a version and an object with the given container/key exists then the version must match the version of the existing object. Concurrent updates for the same custom object still can result in a Conflict (409) even if the version is not provided. Fields with null values will not be saved. Store custom JSON values.

Return type:CustomObject

delete_by_container_and_key(container, key, *, data_erasure=None, version=None, expand=None, force_delete=False)

Delete CustomObject by container and key

Return type:CustomObject

get_by_container_and_key(container, key, *, expand=None)

Get CustomObject by container and key

Return type:CustomObject

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

The query endpoint allows to retrieve custom objects in a specific container or all custom objects.

For performance reasons, it is highly advisable to query only for custom objects in a container by using the container field in the where predicate. Store custom JSON values.

Return type:CustomObjectPagedQueryResponse

query_by_container(container, *, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

Store custom JSON values.

Return type:CustomObjectPagedQueryResponse

Client.inventory

Client.orders

class commercetools.services.orders.OrderService(client)

Bases: commercetools.services.abstract.AbstractService

An order can be created from a order, usually after a checkout process has been completed.

create(draft, *, expand=None)

Creates an order from a Cart.

The cart must have a shipping address set before creating an order. When using the Platform TaxMode, the shipping address is used for tax calculation. An order can be created from a order, usually after a checkout process has been completed.

Return type:Order

delete_by_id(id, version, *, expand=None, data_erasure=None, force_delete=False)

Return type:Order

delete_by_order_number(order_number, version, *, expand=None, data_erasure=None, force_delete=False)

Return type:Order

get_by_id(id, *, expand=None)

Return type:Order

get_by_order_number(order_number, *, expand=None)

In case the orderNumber does not match the regular expression [a-zA-Z0-9_-]+,

it should be provided in URL-encoded format.

Return type:Order

import_(draft)

Create an Order by Import

Return type:Order

order_edit_apply(id, action)

Return type:OrderEdit

order_edit_create(draft, *, expand=None)

OrderEdit are containers for financial changes after an Order has been placed.

Return type:OrderEdit

order_edit_delete_by_id(id, version, *, expand=None, force_delete=False)

Return type:OrderEdit

order_edit_delete_by_key(key, version, *, expand=None, force_delete=False)

Return type:OrderEdit

order_edit_get_by_id(id, *, expand=None)

Return type:OrderEdit

order_edit_get_by_key(key, *, expand=None)

Return type:OrderEdit

order_edit_query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

OrderEdit are containers for financial changes after an Order has been placed.

Return type:OrderEditPagedQueryResponse

order_edit_update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:OrderEdit

order_edit_update_by_key(key, version, actions, *, expand=None, force_update=False)

Return type:OrderEdit

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

An order can be created from a order, usually after a checkout process has been completed.

Return type:OrderPagedQueryResponse

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:Order

update_by_order_number(order_number, version, actions, *, expand=None, force_update=False)

Return type:Order

Client.payments

class commercetools.services.payments.PaymentService(client)

Bases: commercetools.services.abstract.AbstractService

Payments hold information about the current state of receiving and/or refunding money

create(draft, *, expand=None)

To create a payment object a payment draft object has to be given with the request.

Payments hold information about the current state of receiving and/or refunding money

Return type:Payment

delete_by_id(id, version, *, expand=None, data_erasure=None, force_delete=False)

Return type:Payment

delete_by_key(key, version, *, expand=None, data_erasure=None, force_delete=False)

Return type:Payment

get_by_id(id, *, expand=None)

Return type:Payment

get_by_key(key, *, expand=None)

Return type:Payment

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

Payments hold information about the current state of receiving and/or refunding money

Return type:PaymentPagedQueryResponse

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:Payment

update_by_key(key, version, actions, *, expand=None, force_update=False)

Return type:Payment

Client.product_projections

class commercetools.services.product_projections.ProductProjectionService(client)

Bases: commercetools.services.abstract.AbstractService

A projected representation of a product shows the product with its current or staged data.

The current or staged representation of a product in a catalog is called a product projection.

get_by_id(id, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, staged=None)

Gets the current or staged representation of a product in a catalog by ID.

When used with an API client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) product projections.

Return type:ProductProjection

get_by_key(key, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, staged=None)

Gets the current or staged representation of a product found by Key.

When used with an API client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) product projections.

Return type:ProductProjection

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, staged=None)

You can use the product projections query endpoint to get the current or staged representations of Products.

When used with an API client that has the view_published_products:{projectKey} scope, this endpoint only returns published (current) product projections. A projected representation of a product shows the product with its current or staged data. The current or staged representation of a product in a catalog is called a product projection.

Return type:ProductProjectionPagedQueryResponse

search(mark_matching_variants, *, sort=None, limit=None, offset=None, with_total=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, expand=None, fuzzy=None, fuzzy_level=None, staged=None, filter=None, filter_facets=None, filter_query=None, facet=None, text=None)

Search Product Projection

This endpoint provides high performance search queries over ProductProjections. The query result contains the ProductProjections for which at least one ProductVariant matches the search query. This means that variants can be included in the result also for which the search query does not match. To determine which ProductVariants match the search query, the returned ProductProjections include the additional field isMatchingVariant.

Return type:ProductProjectionPagedSearchResponse

suggest(*, sort=None, limit=None, offset=None, with_total=None, fuzzy=None, staged=None, search_keywords=None)

The source of data for suggestions is the searchKeyword field in a product

Return type:ProductProjection

Client.product_types

class commercetools.services.product_types.ProductTypeService(client)

Bases: commercetools.services.abstract.AbstractService

Product Types are used to describe common characteristics, most importantly common custom attributes,

of many concrete products.

create(draft, *, expand=None)

Product Types are used to describe common characteristics, most importantly common custom attributes, of many concrete products.

Return type:ProductType

delete_by_id(id, version, *, expand=None, force_delete=False)

Return type:ProductType

delete_by_key(key, version, *, expand=None, force_delete=False)

Return type:ProductType

get_by_id(id, *, expand=None)

Return type:ProductType

get_by_key(key, *, expand=None)

Return type:ProductType

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None)

Product Types are used to describe common characteristics, most importantly common custom attributes, of many concrete products.

Return type:ProductTypePagedQueryResponse

update_by_id(id, version, actions, *, expand=None, force_update=False)

Return type:ProductType

update_by_key(key, version, actions, *, expand=None, force_update=False)

Return type:ProductType

Client.products

class commercetools.services.products.ProductService(client)

Bases: commercetools.services.abstract.AbstractService

Products are the sellable goods in an e-commerce project on CTP.

This document explains some design concepts of products on CTP and describes the available HTTP APIs for working with them.

create(draft, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None)

To create a new product, send a representation that is going to become the initial staged representation

of the new product in the master catalog. If price selection query parameters are provided, the selected prices will be added to the response. Products are the sellable goods in an e-commerce project on CTP. This document explains some design concepts of products on CTP and describes the available HTTP APIs for working with them.

Return type:Product

delete_by_id(id, version, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, force_delete=False)

Return type:Product

delete_by_key(key, version, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, force_delete=False)

Return type:Product

file_upload(id, fh, *, filename=None, variant=None, sku=None, staged=None)

Uploads a binary image file to a given product variant.

The supported image formats are JPEG, PNG and GIF.

Return type:Product

get_by_id(id, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None)

Gets the full representation of a product by ID.

Return type:Product

get_by_key(key, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None)

Gets the full representation of a product by Key.

Return type:Product

query(*, expand=None, sort=None, limit=None, offset=None, with_total=None, where=None, predicate_var=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None)

You can use the query endpoint to get the full representations of products.

REMARK: We suggest to use the performance optimized search endpoint which has a bunch functionalities, the query API lacks like sorting on custom attributes, etc. Products are the sellable goods in an e-commerce project on CTP. This document explains some design concepts of products on CTP and describes the available HTTP APIs for working with them.

Return type:ProductPagedQueryResponse

update_by_id(id, version, actions, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, force_update=False)

Return type:Product

update_by_key(key, version, actions, *, expand=None, price_currency=None, price_country=None, price_customer_group=None, price_channel=None, locale_projection=None, store_projection=None, force_update=False)

Return type:Product

upload_image(id, fh, *, filename=None, variant=None, sku=None, staged=None)

Uploads a binary image file to a given product variant.

The supported image formats are JPEG, PNG and GIF.

Return type:Product

Client.project

class commercetools.services.project.ProjectService(client)

Bases: commercetools.services.abstract.AbstractService

get()

Return type:Order

update(version, actions, *, force_update=False)

Return type:Project