Use this endpoint whenever a fully calculated and paid or authorized order is created in any third-party system.
The endpoint can create an order on-the-fly in the Commerce Cloud platform by passing the order as JSON payload in the body of the POST request.
Other than the Basket API, this endpoint decouples any relation to other system domains, such as:
The order isn't treated differently than any other orders in the Commerce Cloud platform, including status updates and order exports.
Note*: For the custom attribute to be available for orders, configure it in Business Manager for both Basket and Order objects.
Important*: This endpoint uses the ShopperTokenTsob security scheme. Always check the Security section of the endpoint documentation, which, by default, is hidden.
The checkout must happen before making a request to this endpoint. That means that all sanity checks are applied, the inventory is reserved, the payment is authorized, and the Basket is fully calculated (including all promotions).
After meeting these conditions, it's possible to create the order in the Commerce Cloud platform.
This endpoint can create an order with unknown products, different pricing for known products, unplanned price-adjustments (unrelated to the system's configured promotions), and passing unknown payment and shipping methods.
Note*: There's no lookup or calculation, even if the passed object is configured in the platform.
The endpoint is still coupled to:
The platform does not perform multiplying or dividing operations on this order.
The following fields are summed during runtime on the platform:
Order Level*
adjustedMerchandizeTotalTaxadjustedShippingTotalTaxmerchandizeTotalTaxadjustedTaxproductSubTotalproductTotalshippingTotalTaxorderTotaltaxTotalLine Item Level*
priceAfterItemDiscountpriceAfterOrderDiscountadjustedTaxShipment*
merchandizeTotalTaxproductSubTotalproductTotalshippingTotalTaxTo make sure the fields are summed correctly, the passed orderTotal and taxTotal are compared to the platform's summed orderTotal and taxTotal.
An InvalidOrderTotalException or InvalidTaxTotalException is thrown if the calculation doesn't match.
The orderTotal and taxTotal are calculated as follows:
orderTotal = sum(ProductLineItems.grossPrice) + sum(Shipments.shipmentTotal) - sum(ProductLineItems.PriceAdjustments.grossPrice + Order.PriceAdjustments.grossPrice)taxTotal = sum (ProductLineItems.tax) + sum(Shipments.taxTotal) - sum(ProductLineItems.PriceAdjustments.tax + Order.PriceAdjustments.tax)The order is automatically placed after creation.
The payment status can be set via payload.
All other status can be set via PATCH orders/{orderNo}/status.
If you would like to get a raw Response object use the other createOrders function.
An object containing the options for this method.
A promise of type void.
Use this endpoint whenever a fully calculated and paid or authorized order is created in any third-party system.
The endpoint can create an order on-the-fly in the Commerce Cloud platform by passing the order as JSON payload in the body of the POST request.
Other than the Basket API, this endpoint decouples any relation to other system domains, such as:
The order isn't treated differently than any other orders in the Commerce Cloud platform, including status updates and order exports.
Note*: For the custom attribute to be available for orders, configure it in Business Manager for both Basket and Order objects.
Important*: This endpoint uses the ShopperTokenTsob security scheme. Always check the Security section of the endpoint documentation, which, by default, is hidden.
The checkout must happen before making a request to this endpoint. That means that all sanity checks are applied, the inventory is reserved, the payment is authorized, and the Basket is fully calculated (including all promotions).
After meeting these conditions, it's possible to create the order in the Commerce Cloud platform.
This endpoint can create an order with unknown products, different pricing for known products, unplanned price-adjustments (unrelated to the system's configured promotions), and passing unknown payment and shipping methods.
Note*: There's no lookup or calculation, even if the passed object is configured in the platform.
The endpoint is still coupled to:
The platform does not perform multiplying or dividing operations on this order.
The following fields are summed during runtime on the platform:
Order Level*
adjustedMerchandizeTotalTaxadjustedShippingTotalTaxmerchandizeTotalTaxadjustedTaxproductSubTotalproductTotalshippingTotalTaxorderTotaltaxTotalLine Item Level*
priceAfterItemDiscountpriceAfterOrderDiscountadjustedTaxShipment*
merchandizeTotalTaxproductSubTotalproductTotalshippingTotalTaxTo make sure the fields are summed correctly, the passed orderTotal and taxTotal are compared to the platform's summed orderTotal and taxTotal.
An InvalidOrderTotalException or InvalidTaxTotalException is thrown if the calculation doesn't match.
The orderTotal and taxTotal are calculated as follows:
orderTotal = sum(ProductLineItems.grossPrice) + sum(Shipments.shipmentTotal) - sum(ProductLineItems.PriceAdjustments.grossPrice + Order.PriceAdjustments.grossPrice)taxTotal = sum (ProductLineItems.tax) + sum(Shipments.taxTotal) - sum(ProductLineItems.PriceAdjustments.tax + Order.PriceAdjustments.tax)The order is automatically placed after creation.
The payment status can be set via payload.
All other status can be set via PATCH orders/{orderNo}/status.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other getOrder function.
An object containing the options for this method.
A promise of type Order.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type Order otherwise.
If you would like to get a raw Response object use the other getOrders function.
An object containing the options for this method.
A promise of type OrdersResponse.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type OrdersResponse otherwise.
If you would like to get a raw Response object use the other updateOrder function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderConfirmationStatus function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderExportStatus function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderExternalStatus function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderPaymentInstrument function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderPaymentStatus function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderPaymentTransaction function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderShippingAddress function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
If you would like to get a raw Response object use the other updateOrderShippingStatus function.
An object containing the options for this method.
A promise of type void.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
Orders in status NEW, COMPLETED or CANCELLED can't be changed to status CREATED or FAILED.
Changing the status causes different actions on inventory, coupons, wishlists, and the order itself:
Actions can fail, for example: when inventory is no longer available.
If you would like to get a raw Response object use the other updateOrderStatus function.
An object containing the options for this method.
A promise of type void.
Orders in status NEW, COMPLETED or CANCELLED can't be changed to status CREATED or FAILED.
Changing the status causes different actions on inventory, coupons, wishlists, and the order itself:
Actions can fail, for example: when inventory is no longer available.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type void otherwise.
Generated using TypeDoc
Orders
*# API Overview
Use the Orders API to update order status and order payment status, edit shipping addresses and custom order properties, manage order payment instruments, and get order information.
Authentication & Authorization
The client requesting the order information must have access to the Orders resource. The API requests pass a system-to-system bearer token in the header of the request. The
POST /ordersendpoint uses the ShopperTokenTsob security scheme.You must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see the Authorization Scopes Catalog.
Update Order Statuses
An order uses several status properties to define its workflow state. Some of them are used to trigger internal processes, such as inventory allocation. Others have no default function, but are available for use with customizations.
Order Status
The Order status reflects the overall status of the order. Transitions between order statuses trigger actions such as invoice generation and release of inventory reservations.
Order status can have one of the following values:
created- Default value; denotes that the order was created in the system but is not yet placed.new- Set this value to place the order. When you set this value, the system generates shipment and invoice numbers. After the order is placed, you can’t change the order status tocreatedorfailed.failed- Set this value to fail the order, for example, when you reject the order or when its payment fails. When you set this value, the system releases the order’s inventory reservations and removes any coupon redemptions. You can only set this value if the current order status iscreated. If you change the order status fromfailedtocreated, the system tries to revert the actions taken when it was set tofailed. If inventory isn’t available, the reversion can fail.failed_with_reopen- Set this value to fail the order and reopen the basket, if applicable. The order status is set tofailed.completed- Set this value to mark the order as complete, based on your business process, for example: when the order is fully paid, exported, and shipped.cancelled- Set this value to cancel the order, for example: when the shopper requests it. When you set this value, the system releases the order’s inventory reservations, restores any wishlist items, and removes any coupon redemptions. If you change the order status fromcancelledtocompletedornew, the system tries to revert the actions taken when it was set tocancelled. If inventory isn’t available, the reversion can fail.Confirmation Status
An order confirmation is a document the vendor sends to the shopper. It confirms that the order has been received and accepted. You can use confirmation status to reflect the state of the document, or for other customizations. This field is provided for use in customizations. It isn’t associated with any default functionality.
Confirmation status can have one of the following values:
not_confirmed- Default value.confirmed- Set this value when the order confirmation is sent to the shopper.Export Status
After an order is placed, it must be fulfilled. If your process includes an external fulfillment system, such as a Warehouse Management System, you can use export status to manage the export of order data to the external system. For example, after using the GET /orders endpoint to get order data to export, set the order’s export status to
exported. When identifying orders to export, your query can include orders with export statusreadyand exclude orders with export statusexported.Export status can have one of the following values:
not_exported- Default value.ready- (custom purpose) Set this value when the order is ready for export.exported- Set this value when the order has been exported. When you set this value, the system finalizes the order’s inventory transactions.failed- (custom purpose) Set this value when the order export fails.External Status
The external status field can hold any string value. For example, you can use it for values related to an external fulfillment system. This field is provided for use in customizations, and isn’t associated with any default functionality.
Payment Status
Use payment status to denote whether an order is partially or fully paid. This field is provided for use in customizations, and isn’t associated with any default functionality.
Payment status can have one of the following values:
not_paid- Default value.part_paid- Set this value when the order is partially paid.paid- Set this value when the order is fully paid.Shipping Status
Use shipping status to denote whether an order is partially or fully shipped. This field is provided for use in customizations, and isn’t associated with any default functionality.
Shipping status can have one of the following values:
not_shipped- Default value.part_shipped- Set this value when the order is partially shipped.shipped- Set this value when the order is fully shipped.Example scenarios:
new.failed.exported.shipped.Change Shipping Address
Use the Orders API to update the shipping address on an order.
For example, a shopper places an order, and then sends a request to change the shipping address on that order.
Get Order Data
Use the Orders API system-to-system integration use cases for order retrieval, reporting, dashboards, and so on. You can get information about a single order by specifying the order number, or get information about multiple orders by searching with attribute filters.
You can use the following attribute filters:
You can sort the results in ascending or descending order using the following attributes (default: descending):
Create Orders
Use the createOrders endpoint to create orders from a third-party system, such as a social media platform. Before using the endpoint, you must first complete the checkout process: apply all sanity checks, reserve inventory, authorize payment, apply promotions, and calculate the full cost of the order. Orders made by third-party systems are treated the same as orders made directly through the B2C Commerce platform, including how status updates and exports are handled.
Update Orders
Use the updateOrder endpoint to make changes to custom order attributes.*
For instructions on how to retrieve access token for admin APIs: https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html
Example with admin auth
import { Orders, ClientConfig } from "commerce-sdk"; // or const { Orders, ClientConfig } = require("commerce-sdk"); const clientConfig: ClientConfig = { parameters: { clientId: "XXXXXX", organizationId: "XXXX", shortCode: "XXX", siteId: "XX" } }; token = { access_token: 'INSERT_ACCESS_TOKEN_HERE' }; clientConfig.headers['authorization'] = `Bearer ${token.access_token}`; const ordersClient = new Orders(clientConfig);Last Updated: