POST Create a new basket.
POST /organizations/{organizationId}/baskets
Operation ID: createBasket. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).
Creates a new basket.
The created basket is initialized with default values. Optional JSON data provided in the request body is populated into the created basket. It can be updated with other endpoints offered by the Shopper Baskets API.
Each shopper is limited to one open basket at a time. Attempting to create a second basket for the same customer will result in a 400 Bad Request error with the message: "Customer Baskets Quota Exceeded". A basket is considered "open" upon creation and remains in this state until it is either converted into an order or explicitly deleted. For implementation best practices, see Hybrid Storefront Best Practices for Working with Baskets.
Parameters
siteId(query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.Example: SiteId
RefArchorganizationId(path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character realm identifier and a 3-character instance type identifier.Example
f_ecom_zzxy_prdtaxMode(query, string)Determines how taxes are calculated.
The default value is
internalwhere the tax calculation is done automatically based on internal tax tables. SettingtaxModetoexternalallows manual modification of the tax rates and values. External tax data is mandatory for product line items, option line items, shipping line items, coupon line items, and bonus discount line item. Gift certificate line items are optional and use zero tax rate by default, which can be overwritten. Price adjustments cannot be set because they are either calculated or inherited. Depending on the type, the tax rate is either obtained from the related line item or computed as a prorate of the basket.
Allowed values:internal,external. Default:internal. Example:external.locale(query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameterAccept-Languagefollowing RFC 2616 & RFC 1766. This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.Example: LanguageCountry
en-USExample: CountryCode
USsfdc_usid(header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.
Example:550e8400-e29b-41d4-a716-446655440000.sfdc_shopper_context(header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.
Request body (required)
Media type: application/json. Schema: Basket.
Example: PostBasketBody
{
"customerInfo": {
"email": "shopper@salesforce-test.com",
"customerNo": "000000001"
},
"billingAddress": {
"firstName": "Stephanie",
"lastName": "Miller",
"address1": "104 Presidential Way",
"city": "Woburn",
"postalCode": "01801",
"stateCode": "MA",
"countryCode": "US"
},
"shipments": [
{
"shippingMethod": {
"id": "001"
},
"shippingAddress": {
"firstName": "Agustin",
"lastName": "Estes",
"address1": "4162 Turkey Pen Road",
"city": "New York",
"postalCode": "10016",
"stateCode": "NY",
"countryCode": "US"
}
}
],
"paymentInstruments": [
{
"paymentMethodId": "CREDIT_CARD",
"paymentCard": {
"cardType": "Visa"
}
}
],
"couponItems": [
{
"code": "5ties"
}
],
"productItems": [
{
"productId": "green-umbrella",
"quantity": 3
}
]
}Responses
- 200
The initialized basket.
Media type:
application/json. Schema:Basket.Example: BasketsPostSuccess
{ "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": false, "basketId": "a10ff320829cb0eef93ca5310a", "billingAddress": { "address1": "104 Presidential Way", "city": "Woburn", "countryCode": "US", "firstName": "Stephanie", "fullName": "Stephanie Miller", "id": "bfea663fd3de75d5be3ec02702", "lastName": "Miller", "postalCode": "01801", "stateCode": "MA" }, "channelType": "storefront", "couponItems": [ { "code": "5ties", "couponItemId": "cc6ef43f207bf64099288aec36", "statusCode": "no_applicable_promotion", "valid": true } ], "creationDate": "2019-10-17T08:29:55.340Z", "currency": "USD", "customerInfo": { "customerId": "beQeANXJNsd0xcINsB6cSrobQa", "email": "shopper@salesforce-test.com" }, "lastModified": "2019-10-17T08:29:55.698Z", "merchandizeTotalTax": 30, "orderTotal": 646.76, "paymentInstruments": [ { "amount": 0, "paymentCard": { "cardType": "Visa", "creditCardExpired": false }, "paymentInstrumentId": "b7679bea661819b2de78b9de7d", "paymentMethodId": "CREDIT_CARD" } ], "productItems": [ { "adjustedTax": 30, "basePrice": 199.99, "bonusProductLineItem": false, "gift": false, "itemId": "3d4e28425ce0b3a65b0ac4e163", "itemText": "Green Umbrella - Sustained Edition", "optionItems": [ { "adjustedTax": 0, "basePrice": 0, "bonusProductLineItem": false, "gift": false, "itemId": "ff9452ed11fcf5c80f9143a8f1", "itemText": "We will plant a tree for your order.", "optionId": "plantATree", "optionValueId": "000", "price": 0, "priceAfterItemDiscount": 0, "priceAfterOrderDiscount": 0, "productId": "000", "productName": "Plant a tree.", "quantity": 3, "shipmentId": "me", "tax": 0, "taxBasis": 0, "taxClassId": "standard", "taxRate": 0.05 } ], "price": 599.97, "priceAfterItemDiscount": 599.97, "priceAfterOrderDiscount": 599.97, "productId": "green-umbrella", "productName": "Green Umbrella - Sustained Edition", "quantity": 3, "shipmentId": "me", "tax": 30, "taxBasis": 599.97, "taxClassId": "standard", "taxRate": 0.05 } ], "productSubTotal": 599.97, "productTotal": 599.97, "shipments": [ { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "gift": false, "merchandizeTotalTax": 30, "productSubTotal": 599.97, "productTotal": 599.97, "shipmentId": "me", "shipmentTotal": 646.76, "shippingAddress": { "address1": "4162 Turkey Pen Road", "city": "New York", "countryCode": "US", "firstName": "Agustin", "fullName": "Agustin Estes", "id": "4432af77112f7c2433248a48e8", "lastName": "Estes", "postalCode": "10016", "stateCode": "NY" }, "shippingMethod": { "description": "Order received within 7-10 business days", "id": "001", "name": "Ground", "price": 15.99 }, "shippingStatus": "not_shipped", "shippingTotal": 15.99, "shippingTotalTax": 0.8, "taxTotal": 30.8 } ], "shippingItems": [ { "adjustedTax": 0.8, "basePrice": 15.99, "itemId": "d5ed0e58b8f8b5efe8d617a630", "itemText": "Shipping", "price": 15.99, "priceAfterItemDiscount": 15.99, "shipmentId": "me", "tax": 0.8, "taxBasis": 15.99, "taxClassId": "standard", "taxRate": 0.05 } ], "shippingTotal": 15.99, "shippingTotalTax": 0.8, "taxation": "net", "taxTotal": 30.8 } - 400
Possible reasons:
- the provided payment method is invalid or not applicable.
- the customerId URL parameter does not match the verified customer represented by the JSON Web Token (JWT).
- a new basket cannot be created because the maximum number of baskets per customer would be exceeded.
- the same shipment ID appeared twice in the body.
- the coupon number is not provided.
- a fixed price adjustment was added at order level which is disallowed.
- a promotion ID was used twice, while attempting to add a price adjustment.
- a system promotion ID was used as a manual promotion ID, while attempting to add a price adjustment.
- more than one hundred price adjustments would have been created.
Media type:
application/problem+json. Schema:ErrorResponse.Example: BadRequest
{ "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'." }Example: CustomerBasketQuotaExceededException
{ "title": "Customer Baskets Quota Exceeded", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-baskets-quota-exceeded", "detail": "The maximum number of baskets per customer was exceeded. Please reuse or delete one of the existing baskets (40e91e04aba6e42a6836f79308).", "basketIds": "40e91e04aba6e42a6836f79308" } - 404
Returned if the shipment with the given shipment ID is unknown.
Media type:
application/problem+json. Schema:ErrorResponse.Example: ShipmentNotFound
{ "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/shipment-not-found", "title": "Shipment Not Found", "detail": "The shipping method with ID '123' is unknown or can't be applied to the basket." }