Skip to main content

Cart

The POST /cart operation creates a new external cart. An example of the request body is shown below:

curl --location --request POST 'https://DM_URL/cart' \ --header 'authorization: Bearer eyJ***********Wu0' \ --header 'content-type: application/json' \ --header 'x-company-id: COMPANY_ID' \ --data-raw '{ "name": "Cart Name", "is_scheduled": false, "status": "ready_to_deploy", "changes": [...] }

An example of the response is shown below:

{ "_id": "66c7825b0f206f751df8b3c0", "entity_id": "66c7825b0f206f751df8b3bd" }

entity_id is a key field for other cart related functionality including changes to the cart.

For more information on Cart API's endpoints and data models, see Operation Definitions.

Parent Cart Flow

Some entities in Data Management API depend on the others. For example, to create a discount for products, these products need to already exist in Data Management. A standard flow would be create a products cart, wait for it to be deployed, and, after the deployment, create a discounts cart referencing the products.

To improve efficiency, we have introduced the parent cart flow. The parent cart flow works this way:

  1. Create a products cart.

  2. Create a discounts cart with the products cart as its parent.

  3. Our system saves both carts, but does not deploy the child carts until the parent carts are deployed.

Note

For more complex dependencies, several carts can be created as parent.

An example of this flow is shown below:

Create Products Request Body

curl --location --request POST 'https://DM_URL/cart' \ --header 'authorization: Bearer eyJ***********Wu0' \ --header 'content-type: application/json' \ --header 'x-company-id: COMPANY_ID' \ --data-raw '{ "name": "Cart Products", "is_scheduled": false, "status": "ready_to_deploy", "changes": [...products...] }'

Create Products Response Body

{ "_id": "66c7825b0f206f751df8b310", "entity_id": "77c7825b0f206f751df8b3aa" }

Create Discounts Request Body

curl --location --request POST 'https://DM_URL/cart' \ --header 'authorization: Bearer eyJ***********Wu0' \ --header 'content-type: application/json' \ --header 'x-company-id: COMPANY_ID' \ --data-raw '{ "name": "Cart Discounts", "is_scheduled": false, "status": "ready_to_deploy", "changes": [...discounts...], "cart_deps_flow": { "deps_type": "manual", "parent_cart_entity_ids": [ "77c7825b0f206f751df8b3aa" // entity_id from products cart response ] } }'

entity_reference_id

Each entity created must have an entity_reference_id field. This field can be used to modify the entity in the future or to reference it in other entities. To reference an entity, the property must start with “ref__.”

An example of a reporting category (major) creation is shown below:

{ "name": "Reporting Category Major", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "entity_type": "reporting-category", "entity_reference_id": "reference_reporting_category_011", "name": "Drinks", "is_major": true, "minor_reporting_category_entity_ids": [] } ] }

An example of a reporting category (minor) creation is shown below:

{ "name": "Reporting Category Minor", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "entity_type": "reporting-category", "entity_reference_id": "reference_reporting_category_012", "name": "Drinks - Minor 1", "is_major": false, "ref__major_reporting_category_entity_id": "reference_reporting_category_011" } ], "cart_deps_flow": { "deps_type": "manual", "parent_cart_entity_ids": ["<ENTITY_ID_OF_CART_WITH_MAJOR>"] } }

Instead of a major_reporting_category_entity_id field with the our system's internal entity_id, we can provide ref__major_reporting_category_entity_id with entity_reference_id, which is an external integrator identifier.

An example of a reporting category (major) update is shown below:

{ "name": "Reporting Category Major (update)", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "entity_type": "reporting-category", "entity_reference_id": "reference_reporting_category_011", "name": "Drinks - updated" } ] }

Price Management

To simplify price management, it has been combined with the product. An example is shown below:

{ "name": "Set prices for a product", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "entity_reference_id": "001007", "entity_type": "product", "prices": [ { "type": "standard", "unit_price": 5.41, "site_ids": [ "63989903fd53eed6ee9caa27", "63989903fd53eed6ee9caa28" ] }, { "type": "standard", "unit_price": 2.15, "site_ids": [ "63989903fd53eed6ee9caa29" ] } ] } ] }

Sample Code

Create Product with Prices and Availability Request Body

{ "name": "Cart", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "name": "Product7", "product_id": "001007", "product_type": "standard", "entity_reference_id": "001007", "is_open_price": true, "entity_type": "product", "reporting_category": { "ref__major_reporting_category_entity_id": "<EXTERNAL_REFERENCE>", "ref__minor_reporting_category_entity_id": "<EXTERNAL_REFERENCE>" }, "site_values_patch": { "is_active": [ { "value": true, "site_ids": [ "{{site_id1}}", "{{site_id2}}" ] } ], "tax_group_entity_id": [ // can be prefixed with ref__ to use external references { "value": "<ENTITY_ID>", "site_ids": [ "{{site_id1}}", "{{site_id2}}" ] } ], "item_description": [ { "value": "Some value 1", "site_ids": [ "{{site_id1}}" ] }, { "value": "Some value 2", "site_ids": [ "{{site_id2}}" ] } ] }, "prices": [ { "type": "standard", "unit_price": 5.41, "site_ids": [ "{{site_id1}}" ] }, { "type": "standard", "unit_price": 2.15, "site_ids": [ "{{site_id2}}" ] } ] } ], "cart_deps_flow": { // OPTIONAL. This is needed if we are not sure reporting categories have already been deployed "deps_type": "manual", "parent_cart_entity_ids": [ "<MAJOR_REPORTING_CAT_CART>", "<MINOR_REPORTING_CAT_CART>" ] } }

Create Discount Request Body

{ "name": "Cart Discounts", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "name": "Discount 4", "entity_type": "discount-definition", "type": "discount", "entity_reference_id": "0011009", "code": "Test_code_0011009", "calc": { "type": "fixed_amount", "value": 1, "max_value": 0, "use_item_price_as_discount_amount": false, "calculate_discount_against_price_of_alternative_item": false }, "customer_info_prompts": [], "apply_type": "manual", "where_available": [ "order", "tender", "mobile_ordering", "barcode_scan" ], "amount_application_rule": "gross_item_amount", "apply_criteria": { "selected_tags_entity_ids": [], "ref__selected_product_entity_ids": [ "001008" ], "condition": "include" }, "site_values_patch": { "is_active": [ { "value": true, "site_ids": [ "{{site_id1}}", "{{site_id2}}" ] } ], "calc": [ { "value": { "type": "fixed_amount", "value": 2, "max_value": 0, "use_item_price_as_discount_amount": false, "calculate_discount_against_price_of_alternative_item": false }, "site_ids": [ "{{site_id2}}" ] } ] } } ] }

Enable Sequential Cart Deployment

Sequential Cart Deployment allows the following functionality:

  • It has a 10 second delay for each cart deployment.

  • If multiple cart deployments contain the same entity_reference_id, our system makes the oldest cart a parent of the newer cart.

To ensure multiple requests are processed in sequential order, complete the following:

  1. Contact our support team to activate this feature.

  2. After the feature is activated in our system, add the header x-client-current-date to each request. The value for this header is the current date and time that the request is sent.

A request example using x-client-current-date is shown below.

curl --location -g --request POST '${DM_API_URL}/cart' \ --header 'authorization: Bearer ${TOKEN}' \ --header 'content-type: application/json' \ --header 'x-company-id: ${COMPANY_ID}' \ --header 'x-client-current-date: 2023-11-03T19:43:03.858Z' \ --data-raw '{ "name": "Cart", "is_scheduled": false, "status": "ready_to_deploy", "changes": [ { "entity_reference_id": "11", "entity_type": "product", "prices": [ { "type": "standard", "unit_price": 375, "site_ids": [ "${SITE_ID}" ] } ] } ] }'

See also: