Shopper Baskets V2

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
```
RefArch
```
organizationId (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_prd
```
taxMode (query, string)
Determines how taxes are calculated.

The default value is internal where the tax calculation is done automatically based on internal tax tables. Setting taxMode to external allows 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.
temporary (query, boolean) If set to true, the basket created is a temporary basket.
Default: false.
populateCustomerDetails (query, boolean)
If set to true, the system invokes the dw.order.populateCustomerDetails hook.

By default, the hook retrieves the registered customer's default address or first saved address, and payment instrument. The hook then uses this information to populate the basket:
- If no shipping address is specified, the shipping address is set to the customer's saved address.
- If no billing address is specified, the billing address is set to the customer's saved address.
- If no payment instrument is specified, the payment instrument is set to the customer's saved payment instrument.
This behavior can be customized by overriding the hook.

Default: false. Example: false.
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 parameter Accept-Language following 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-US
```
Example: CountryCode
```
US
```
sfdc_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_dw_dnt (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.
Allowed values: 0, 1. Example: 1.
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.
a new temporary basket cannot be created because the maximum number of temporary 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"
}

Example: TemporaryBasketQuotaExceededException

{
  "title": "Customer Temporary Baskets Quota Exceeded,",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-temporary-baskets-quota-exceeded",
  "detail": "The maximum number of temporary baskets per customer was exceeded. Please reuse or delete one of the existing temporary baskets (40e91e04aba6e42a6836f79308, 73ca0f0860a67df946782c2688).",
  "basketIds": "40e91e04aba6e42a6836f79308, 73ca0f0860a67df946782c2688"
}

404 Returned if the shipment with the given shipment ID is unknown.

Media type: application/problem+json.

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."
}