--- schema_version: "1" id: 46b066b88b9c34eef4bdef9f91630141960f628f4dd0b55289de70edd53f7d51 title: Shopper Baskets V2 collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-baskets-v2.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2 source_site: developer.salesforce.com content_type: documentation content_hash: 6c7117e6ddb4787d6e8708642816826b65928359eea7fd85877db283bc389bce products: - B2C Commerce API - Salesforce APIs --- Shopper Baskets V2 # Shopper Baskets V2 [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-baskets-v2/shopper-baskets-oas-v2-public.yaml) ## API Overview Shopper Baskets V2 provides all Shopper Basket V1 functionality and adds support for temporary baskets. Temporary baskets can perform calculations to generate totals, line items, promotions, and item availability without affecting the shopper’s storefront cart, and you can use those calculations for temporary basket checkout. You can also use a temporary basket for an immediate order request. **Note**: `dw.ocapi.shop.basket.beforePOST` hook is no longer supported and is replaced by the `dw.ocapi.shop.basket.beforePOST_v2` hook. Use the Shopper Baskets API to create a basket in the B2C Commerce system and populate it with all the data required to ready the basket for checkout. To create a basket, start with the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint. The endpoint creates the basket in the B2C Commerce system and returns a JSON representation of the basket with a `basketId` property. If you provide the JSON for a prepopulated basket to the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint, you can create a basket using a single API request. You can also create a basket and gradually populate it with data using subsequent API requests that reference the same `basketId`. The gradual approach allows you to validate the input data as you go. The Shopper Baskets API includes endpoints to populate each part of a basket separately, including: * Billing address * Customer information * Line items * Products * Coupons * Gift certificates * Payment methods * Price books * Shipments * Taxation (for items and the basket itself) In addition to creating a basket, the main `/baskets` resource offers endpoints to get, transfer, merge, and delete baskets, depending on the HTTP method that you use and the parameters that you supply. These endpoints can you help you handle a variety of complex scenarios, such as when a user starts shopping as a guest and then logs in before checkout. You can also use the main `/baskets` resource to add custom properties to your basket, prefixed with `c_` (example: `c_faxNumber`). When your basket is fully populated, you can use its `basketId` property to create an order with the [Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary). For more detail on building baskets, see [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html). ### Authentication & Authorization The client requesting the basket information must have access to the `/baskets` resource. The Shopper Baskets API requires a shopper access token from the Shopper Login and API Access Service (SLAS). For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides. You must include `sfcc.shopper-baskets-orders` or `sfcc.shopper-baskets-orders.rw` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) The following resources require an Account Manager OAuth token with a client ID: * `/baskets/{basketId}/taxes` * `/baskets/{basketId}/items/{itemId}/taxes` * `/baskets/{basketId}/price-books` ### Customization #### Custom Properties This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html) #### Hooks For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) ### Response Details #### Personalization Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching) #### Caching Responses from this API are not cached. Basket data is stateful and unique to each shopper session. #### Timeouts Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Use Cases #### Create a Basket Create a new basket for the shopper. ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2/organizations/{organizationId}/baskets?siteId=RefArch" \ -X POST \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{}' ``` #### Add an Item to a Basket Add a product to an existing basket. ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2/organizations/{organizationId}/baskets/{basketId}/items?siteId=RefArch" \ -X POST \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '[{ "productId": "25695327M", "quantity": 1 }]' ``` #### Basket Calculation Unless you’re using [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), each modification to a basket triggers the following calculations: 1. Calculate product prices: * Iterate through the product line items and determine the base price of each using its price model. If multiple price books apply to a product, the lowest price is used. * Calculate product option line item prices using the product option model. * For bonus products, check dependent adjustments in the basket to determine the price. 2. Iterate through the gift certificate line items and calculate the price of each by multiplying the base price by the quantity. 3. Recalculate for all promotions, adding and removing them as appropriate. 4. Apply product-specific shipping costs. 5. Calculate the total shipping cost. 6. Recalculate for all promotions, adding and removing them as appropriate. 7. Calculate prices for products added by the promotion engine. 8. Calculate taxes using line item tax class codes. * For internal tax mode, use the tax tables. * For external tax mode, use the tax rates returned by the tax API endpoints. 9. Calculate the order’s net, tax, and gross totals by adding up the line totals. #### External Taxation The B2C Commerce API calculates taxes internally using tax tables. If you want to integrate with a third-party tax provider, or calculate tax on your own, you can use the external taxation feature to add a taxation rate and optional taxation value. When setting a taxation rate, the taxation is calculated for this specific rate. If you pass a value, this value is used as taxation value, as well, without recalculation. To use this feature, set the `taxMode` parameter to `external` when creating the basket. When using external taxation, you must set a tax rate either in one request to the `/baskets/{basketId}/taxes` or with separate requests for each line item, using `/baskets/{basketId}/items/{lineItemId}/taxes`. If the tax mode of a basket is set to `external`, a tax item is required for all line items even for zero-tax items to avoid oversights. #### External Taxation with Hooks Enabled To use external tax calculation with [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), use the following API methods in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook): * `dw.order.LineItemCtnr#isExternallyTaxed`: Returns true if the basket was created with `taxMode = external` * `dw.order.TaxMgr#applyExternalTax`: Applies externally set tax rates to the given basket. Only use when `dw.order.LineItemCtnr#isExternallyTaxed` returns true. The following example shows an implementation of external tax calculation with hooks enabled in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook): ```javascript exports.calculate = function (basket) { if ( basket.isExternallyTaxed() ) { TaxMgr.applyExternalTaxation( basket ); // apply the external tax calculation based on the tax rates set by the SCAPI external taxation APIs } else { // calculation with tax tables or customization } } ``` ### Temporary Baskets A temporary basket is populated with all the data required to ready the basket for checkout, but differs from a shopper basket in the following ways: * Basket lifetime is limited to 15 minutes. * The shopper can have up to 10 (default 4) temporary baskets, which can be configured via Basket Preferences (Sites -> Merchant Tools -> Basket Preferences) and specifying the preference **Temporary Baskets per Customer**. * Available to all shoppers (guest and registered shoppers), as well as agents. To create a temporary basket, set the `temporary` parameter to `true` with the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint. To promote a temporary basket by clearing its `isTemporary` flag, use the [Promote basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=promoteTemporaryBasket) endpoint. ### Related APIs * [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) — Place an order from a completed basket. * [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) — Retrieve payment method configuration for checkout. **Version:** 2.13.4 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * `RegisteredShopperToken` (oauth2) `RegisteredShopperToken` is a child of the `ShopperToken` security scheme and restricts access to a **registered (authenticated) shopper**. Access is only granted to a shopper token that represents a registered shopper; a guest shopper token is rejected. Endpoints secured with `RegisteredShopperToken` operate on identity-bound resources of a registered shopper, such as their addresses, payment instruments, password, or saved product lists. Besides these endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `RegisteredShopperToken`. To get a `RegisteredShopperToken`, the shopper must authenticate with SLAS (for example, through the authorization code flow or the [login endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer)). For details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * `ShopperTokenTaob` (oauth2) `ShopperTokenTaob` (Taob = trusted agent on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTaob` allows you to access Shopper API endpoints, including OCAPI and Salesforce Commerce API for headless applications. Besides endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `ShopperTokenTaob`. To get a `ShopperTokenTaob` token, a `Taob` session needs to be created first (see [getTrustedAgentAuthorizationToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAuthorizationToken)). Afterwards the `ShopperTokenTaob` token can be gained (see [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAccessToken)). For more information regarding the `Taob` flow see also [Trusted Agent Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html). * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-agent/token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints ## Operations ### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html#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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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." } ``` ### POST Transfer an existing basket. `POST /organizations/{organizationId}/baskets/actions/transfer` Operation ID: `transferBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Transfer the previous shopper's basket to the current shopper by updating the basket's owner. No other values change. You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token. This endpoint provides different methods for handling the scenario in which both a previous guest shopper and the current registered shopper have an active basket attached, and utilizes the `merge` parameter as follows: * `true` (recommended): Triggers a merge hook for graceful handling and prevents 409 status returns. For more information, refer to the `merge` parameter documentation. * `false`: Either overrides the basket of the current registered shopper or returns a 409 response, and allows you to choose between the options explained below. If you call the endpoint with `merge=false` and the current shopper has an active basket, you have two options using the `overrideExisting` parameter. Setting it to `true` deletes the registered user's basket, while setting it to `false` returns a `BasketTransferException` (HTTP status 409), after which you can choose how to proceed: * Keep the current shopper's active basket. * Merge the previous and current shoppers' baskets by calling the `baskets/actions/merge` endpoint. * Force the transfer by calling the `baskets/actions/transfer` endpoint again, with the parameter `overrideExisting=true`. Forcing the transfer deletes the current shopper's active basket. A successful response provides the transferred (and merged) current basket. However, if neither the previous nor current shopper had an active basket, a 204 (No Content) response is returned. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `overrideExisting` (query, boolean) If the current shopper has no active basket, this parameter is ignored. If the current shopper has an active basket, this parameter controls the behavior: * `false` (default): Return a BasketTransferException (HTTP status 409). The basket owner doesn't change. * `true`: Force the transfer by deleting the current shopper's active basket and making the current shopper the owner of the previous shopper's basket. Returns the transferred basket (HTTP status 200). Default: `false`. Example: `false`. * `merge` (query, boolean) This parameter controls the behavior: \- `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration). - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists. The hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown in this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f). There are four possible use cases: a) Guest basket and registered basket exist The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket). b) Guest basket exists but no registered basket exists The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket). c) No guest basket exists but a registered basket exists The registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null passed to the hook). d) Neither basket exists The hook dw.order.mergeBasket is not called. The API returns the current basket (after executing dw.order.mergeBasket). Default: `false`. Example: `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** The current basket. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **204** The operation was successful. No current basket was returned because neither the previous nor current shopper had an active basket attached that could be transferred. * **403** The call returns this error if no SLAS token for a registered shopper is available. Media type: `application/json`. Schema: `ErrorResponse`. _Example: ForbiddenMissingPrevCustomerInfo_ ``` { "title": "Forbidden", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "detail": "Your access-token is valid, but it contains no previous customer to process this action." } ``` * **409** The call returns this response when the `merge` request parameter is set to `false` and one of the following cases applies: * The previous shopper has no active basket. * The current shopper has an active basket and the `overrideExisting` query parameter is set to `false` (default value). Media type: `application/json`. Schema: `ErrorResponse`. _Example: SourceBasketException_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/no-source-basket-exception", "title": "Conflict", "detail": "The previous customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket." } ``` _Example: BasketTransferException_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-transfer-basket-already-exists-exception", "title": "Conflict", "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has an active basket." } ``` ### POST Merge baskets. `POST /organizations/{organizationId}/baskets/actions/merge` Operation ID: `mergeBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). ( DEPRECATED ) Instead of using this endpoint, we recommend using the `/baskets/actions/transfer` endpoint with the `merge=true` parameter, because the transfer endpoint offers greater customization by invoking a hook, allowing for adjustments if the default implementation does not process the merge as expected. Merge data from the previous shopper's basket into the current shopper's active basket and delete the previous shopper's basket. This endpoint doesn't merge Personally Identifiable Information (PII). You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token. After the merge, all basket amounts are recalculated and totaled, including lookups for prices, taxes, shipping, and promotions, unless hooks are enabled. The following information is merged: * custom attributes on the basket and on all copied records * product items * gift certificate items * coupon items * shipments * ad-hoc price adjustments To control the merging of products that exist in both baskets, use the `productItemMergeMode` parameter. By default, the higher of the two basket quantities is used for each product. Products in both baskets are considered to be the same when all of the following values match (if one product doesn't have a value, the other product is a match only if it also doesn't have that value): * shipment * productId * option values * wishlist reference * inventory list id * gift flag & message * ad-hoc price adjustments If any of the listed values don't match, then the item in the previous shopper's basket is copied to a new line item in the current shopper's basket. If the listed values all match, but the matching products have different values for any custom attribute, the merged line item keeps the custom attribute value from the current shopper's basket. A success response contains the current shopper's active basket. The previous guest shopper's active basket is deleted. If the current shopper doesn't have an active basket, and the createDestinationBasket request parameter is false, then the merge request returns a BasketMergeException (HTTP status 409). You can proceed with one of these options: * Transfer the previous shopper's active basket to the current logged-in shopper by calling the `baskets/transfer` endpoint. * Force the merge by calling the `baskets/merge` endpoint again, with the parameter `createDestinationBasket=true`. Forcing the merge creates a new basket for the current shopper and copies information from the previous shopper's basket into it. Because the merge doesn't copy all basket data, a forced merge is not the same as a transfer. For example, the new basket doesn't contain any Personally Identifiable Information (PII) from the previous basket. #### before merge | Previous Shopper's Basket, SKU: Quantity, Custom Attributes | Current Shopper's Basket, SKU: Quantity, Custom Attributes | | --- | --- | | SKU\_A: 5 SKU\_B: 3 SKU\_C: 4 c\_customAttr\_1: 'ABC' c\_customAttr\_2: 'DEF' | SKU\_A: 2 SKU\_D: 6 SKU\_E: 7 c\_customAttr\_1: 'UVW' c\_customAttr\_3: 'XYZ' | #### after merge - (previous shopper's basket is deleted) | productItemMergeMode | Current Shopper's Basket - SKU: Quantity, Custom Attributes | | --- | --- | | sum\_quantities | SKU\_A: 7 SKU\_B: 3 SKU\_C: 4 SKU\_D: 6 SKU\_E: 7 c\_customAttr\_1: 'UVW' c\_customAttr\_2: 'DEF' c\_customAttr\_3: 'XYZ' | | higher\_quantity | SKU\_A: 5 SKU\_B: 3 SKU\_C: 4 SKU\_D: 6 SKU\_E: 7 c\_customAttr\_1: 'UVW' c\_customAttr\_2: 'DEF' c\_customAttr\_3: 'XYZ' | | saved\_quantity | SKU\_A: 2 SKU\_B: 3 SKU\_C: 4 SKU\_D: 6 SKU\_E: 7 c\_customAttr\_1: 'UVW' c\_customAttr\_2: 'DEF' c\_customAttr\_3: 'XYZ' | | separate\_item | SKU\_A: 5 SKU\_B: 3 SKU\_C: 4 SKU\_A: 2 SKU\_D: 6 SKU\_E: 7 c\_customAttr\_1: 'UVW' c\_customAttr\_2: 'DEF' c\_customAttr\_3: 'XYZ' | #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `createDestinationBasket` (query, boolean) If the current shopper has an active basket, this parameter is ignored. If the current shopper has no active basket, this parameter controls the behavior: * `false` (default): Return a BasketMergeException (HTTP status 409). * `true`: Force the merge by creating a basket for the current shopper and copying information from the previous shopper's basket into it. Return success (HTTP status 200). Default: `false`. * `productItemMergeMode` (query, string) This parameter controls the quantity calculation for products that exist in both baskets. * higher\_quantity (default): Compare the product's quantities in each basket, and use the higher value. * sum\_quantities: Use the sum of the product's quantities from both baskets. * saved\_quantity: Use the product's quantity in the current shopper's active basket. Ignore the quantity from the previous shopper's basket. * separate\_item: Add a separate product item to the current shopper's basket for the quantity in the previous shopper's basket. Allowed values: `higher_quantity`, `sum_quantities`, `saved_quantity`, `separate_item`. Default: `higher_quantity`. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** The current shopper's active basket, including items merged from the previous shopper's basket. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **403** The call returns this error if no SLAS token for a registered shopper is available. Media type: `application/json`. Schema: `ErrorResponse`. _Example ForbiddenMissingPrevCustomerInfo: same as POST /organizations/{organizationId}/baskets/actions/transfer 403 response._ * **409** The call returns this response in either of these cases: * The previous shopper has no active basket. * The current shopper has no active basket and the `createDestinationBasket` query parameter was `false` (default value). Media type: `application/json`. Schema: `ErrorResponse`. _Example SourceBasketException: same as POST /organizations/{organizationId}/baskets/actions/transfer 409 response._ _Example: BasketMergeException_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-merge-no-current-basket-exception", "title": "Conflict", "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket." } ``` ### GET Retrieve an existing basket. `GET /organizations/{organizationId}/baskets/{basketId}` Operation ID: `getBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Gets a basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` * `expand` (query, array of string, style: form, explode: false) Expands the response with additional data. * payment\_references: Adds a `paymentReference` object to each `paymentInstrument`, holding data regarding the payment with the external payment gateway. If Salesforce Payments is not enabled, this expansion has no effect. * approaching\_discounts: The endpoint returns the approachingDiscounts array on the basket, which contains order and shipping discount entries. If you don't provide this parameter, the approachingDiscounts field isn't included in the response. Items: Allowed values: `payment_references`, `approaching_discounts`. Example: `payment_references`. _Example_ ``` [ "payment_references", "approaching_discounts" ] ``` * `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`. * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success, the response body contains the retrieved basket. Media type: `application/json`. Schema: `Basket`. _Example: GetBasket_ ``` { "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, "deliveryWindow": { "startAt": "2026-05-04T14:00:00Z", "endAt": "2026-05-07T22:00:00Z" }, "gift": false, "merchandizeTotalTax": 30, "orderCutoffAt": "2026-04-27T14:00:00Z", "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, "deliveryWindow": { "startAt": "2026-05-04T14:00:00Z", "endAt": "2026-05-07T22:00:00Z" }, "orderCutoffAt": "2026-04-27T14:00:00Z" }, "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 } ``` _Example: GetBasketWithOrderApproachingDiscount_ ``` { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": false, "basketId": "a10ff320829cb0eef93ca5310a", "channelType": "storefront", "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, "productItems": [ { "adjustedTax": 30, "basePrice": 199.99, "bonusProductLineItem": false, "gift": false, "itemId": "3d4e28425ce0b3a65b0ac4e163", "itemText": "Green Umbrella - Sustained Edition", "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, "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, "approachingDiscounts": [ { "type": "order", "conditionThreshold": 700, "merchandiseTotal": 599.97, "discount": { "type": "percentage", "percentage": 0.15 }, "promotionLink": { "promotionId": "15off700", "name": "15% off $700 orders", "calloutMsg": "Spend $100 more to save 15%!", "title": "15% off $700 orders", "link": "/s/RefArch/promotions/15off700" } } ] } ``` _Example: GetBasketWithShippingApproachingDiscount_ ``` { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": false, "basketId": "a10ff320829cb0eef93ca5310a", "channelType": "storefront", "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, "productItems": [ { "adjustedTax": 30, "basePrice": 199.99, "bonusProductLineItem": false, "gift": false, "itemId": "3d4e28425ce0b3a65b0ac4e163", "itemText": "Green Umbrella - Sustained Edition", "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, "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, "approachingDiscounts": [ { "type": "shipping", "conditionThreshold": 750, "merchandiseTotal": 599.97, "discount": { "type": "amount", "amount": 15.99 }, "promotionLink": { "promotionId": "freeship750", "name": "Free shipping over $750", "calloutMsg": "Add $150 more for free shipping!", "title": "Free shipping over $750", "link": "/s/RefArch/promotions/freeship750" }, "shipmentId": "me", "shippingMethods": [ { "id": "001", "name": "Ground", "description": "Order received within 7-10 business days", "price": 15.99 }, { "id": "002", "name": "2-Day Express", "description": "Order received in 2 business days", "price": 20.99 } ] } ] } ``` * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Delete a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}` Operation ID: `deleteBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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. #### Responses * **204** Success, without a body. * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}` Operation ID: `updateBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates a basket. Only the currency of the basket, source code, the custom properties of the basket, and the shipping items will be considered. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: BasketPatch_ ``` { "c_textValue": "oak" } ``` #### Responses * **200** Success, the response body contains the updated basket. Media type: `application/json`. Schema: `Basket`. _Example: BasketPatch_ ``` { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": false, "basketId": "a10ff320829cb0eef93ca5310a", "billingAddress": { "address1": "104 Presidential Way", "city": "Woburn", "countryCode": "US", "firstName": "Stephanie", "fullName": "Stephanie Miller", "id": "5f695b6f4bb63cb686483d65a0", "lastName": "Miller", "postalCode": "01801", "stateCode": "MA" }, "channelType": "storefront", "couponItems": [ { "code": "5ties", "couponItemId": "7800e0f611dac6caf77afb9df9", "statusCode": "no_applicable_promotion", "valid": true } ], "creationDate": "2019-10-17T08:53:30.993Z", "currency": "USD", "customerInfo": { "customerId": "beQeANXJNsd0xcINsB6cSrobQa", "email": "shopper@salesforce-test.com" }, "lastModified": "2019-10-17T08:53:35.747Z", "merchandizeTotalTax": 30, "orderTotal": 646.76, "paymentInstruments": [ { "amount": 0, "paymentCard": { "cardType": "Visa", "creditCardExpired": false }, "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d", "paymentMethodId": "CREDIT_CARD" } ], "productItems": [ { "adjustedTax": 30, "basePrice": 199.99, "bonusProductLineItem": false, "gift": false, "itemId": "43c38652bc3844e14cd482ff28", "itemText": "Green Umbrella - Sustained Edition", "optionItems": [ { "adjustedTax": 0, "basePrice": 0, "bonusProductLineItem": false, "gift": false, "itemId": "b4ff13039bc7abd1b9d933b871", "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": "193e99bc1205b870cebd36d970", "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": "ac7a3b62dc1df8de898d7a2141", "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, "c_textValue": "oak" } ``` * **400** Possible reasons: * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). * the basket cannot be updated because the requested currency is not supported by the site. * the given shipping item ID is null or empty. * a few shipping items with the same item ID are provided. * the provided code is not currently active. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** Possible reasons: * the basket with the given basket ID is unknown. * the shipping item with the given item ID is unknown for the basket. * the provided code was not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Promote a temporary basket by clearing its isTemporary flag. `POST /organizations/{organizationId}/baskets/{basketId}/actions/promote` Operation ID: `promoteTemporaryBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Clears the `isTemporary` flag on a temporary basket (`isTemporary = true`). The basket UUID is preserved. For regular shopper baskets, the result satisfies `isStorefrontBasket`; for agent baskets (`isAgentBasket = true`), the `isTemporary` flag is cleared but the basket remains an agent basket — it does not become a storefront basket. **Agent baskets:** Because agent baskets do not occupy the customer's storefront basket slot after promotion, conflict resolution is skipped entirely. The `merge` and `overrideExisting` parameters are ignored when promoting an agent basket. For non-agent baskets, if the shopper already has a storefront basket, this endpoint uses the `merge` parameter to control the behavior: * `true` (recommended): Executes the `dw.order.mergeBasket` hook to fold the pre-existing storefront basket's contents into the promoted basket. * `false`: Either overrides the pre-existing storefront basket or returns a `409` response, depending on the `overrideExisting` parameter. If `merge=false` and the shopper has a pre-existing storefront basket, the `overrideExisting` parameter controls the behavior: * `false` (default): Returns a `BasketNotPromotableException` (HTTP status 409). * `true`: Deletes the pre-existing storefront basket and completes the promotion. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `overrideExisting` (query, boolean) If the current shopper has no active basket, this parameter is ignored. If the current shopper has an active basket, this parameter controls the behavior: * `false` (default): Return a BasketTransferException (HTTP status 409). The basket owner doesn't change. * `true`: Force the transfer by deleting the current shopper's active basket and making the current shopper the owner of the previous shopper's basket. Returns the transferred basket (HTTP status 200). Default: `false`. Example: `false`. * `merge` (query, boolean) This parameter controls the behavior: \- `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration). - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists. The hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown in this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f). There are four possible use cases: a) Guest basket and registered basket exist The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket). b) Guest basket exists but no registered basket exists The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket). c) No guest basket exists but a registered basket exists The registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null passed to the hook). d) Neither basket exists The hook dw.order.mergeBasket is not called. The API returns the current basket (after executing dw.order.mergeBasket). 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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** The basket's `isTemporary` flag has been cleared. For regular shopper baskets the result is a storefront basket; agent baskets remain agent baskets. Media type: `application/json`. Schema: `Basket`. _Example: BasketPutStorefront_ ``` { "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": "callcenter", "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 } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **409** The call returns this response when the `merge` request parameter is set to `false` and the shopper has a pre-existing storefront basket and `overrideExisting` is set to `false` (default value). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotPromotableException_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-promotable-exception", "title": "Conflict", "detail": "The basket with ID 'a10ff320829cb0eef93ca5310a' cannot be promoted to a storefront basket in its current state." } ``` #### Extension points * `dw.order.mergeBasket` (service-logic) Called when merge=true and the shopper has a pre-existing storefront basket. Merges the pre-existing basket into the promoted basket. * `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.beforePOST` (before) Called before promoting the temporary basket. The default implementation does nothing. * `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.afterPOST` (after) Called after promoting the temporary basket. The default implementation calls the calculate hook, which recalculates the promoted basket. * `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.modifyPOSTResponse` (modifyResponse) Called to modify the basket returned in the response after promotion. The default implementation does nothing. ### PUT Designate a basket as an agent basket. `PUT /organizations/{organizationId}/baskets/{basketId}/agent` Operation ID: `updateAsAgentBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw). Marks a basket as an agent basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` #### Responses * **200** Success, the response body contains basket that is set as an agent basket. Media type: `application/json`. Schema: `Basket`. _Example: BasketPutAgent_ ``` { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": true, "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** Marking this basket as an agent basket would exceed the open agent basket limit for the basket customer. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CustomerInfoJwtMismatch: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Add a billing address to a basket. `PUT /organizations/{organizationId}/baskets/{basketId}/billing-address` Operation ID: `updateBillingAddressForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Sets the billing address of a basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` * `useAsShipping` (query, boolean) When true, the address is also used as the shipping address. * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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: `OrderAddress`. _Example: BillingAddressPut_ ``` { "firstName": "Stephanie", "lastName": "Miller", "address1": "385 Prospect Valley Road", "city": "Woburn", "postalCode": "01801", "stateCode": "MA", "countryCode": "US" } ``` #### Responses * **200** Success, the response body contains basket with the added billing address. Media type: `application/json`. Schema: `Basket`. _Example: BillingAddress_ ``` { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "agentBasket": false, "basketId": "a10ff320829cb0eef93ca5310a", "billingAddress": { "address1": "385 Prospect Valley Road", "city": "Woburn", "countryCode": "US", "firstName": "Stephanie", "fullName": "Stephanie Miller", "id": "5f695b6f4bb63cb686483d65a0", "lastName": "Miller", "postalCode": "01801", "stateCode": "MA" }, "channelType": "storefront", "couponItems": [ { "code": "5ties", "couponItemId": "7800e0f611dac6caf77afb9df9", "statusCode": "no_applicable_promotion", "valid": true } ], "creationDate": "2019-10-17T08:53:30.993Z", "currency": "USD", "customerInfo": { "customerId": "beQeANXJNsd0xcINsB6cSrobQa", "email": "shopper@salesforce-test.com" }, "lastModified": "2019-10-17T08:53:35.747Z", "merchandizeTotalTax": 30, "orderTotal": 646.76, "paymentInstruments": [ { "amount": 0, "paymentCard": { "cardType": "Visa", "creditCardExpired": false }, "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d", "paymentMethodId": "CREDIT_CARD" } ], "productItems": [ { "adjustedTax": 30, "basePrice": 199.99, "bonusProductLineItem": false, "gift": false, "itemId": "43c38652bc3844e14cd482ff28", "itemText": "Green Umbrella - Sustained Edition", "optionItems": [ { "adjustedTax": 0, "basePrice": 0, "bonusProductLineItem": false, "gift": false, "itemId": "b4ff13039bc7abd1b9d933b871", "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": "193e99bc1205b870cebd36d970", "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": "ac7a3b62dc1df8de898d7a2141", "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** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Add a coupon to a basket. `POST /organizations/{organizationId}/baskets/{basketId}/coupons` Operation ID: `addCouponToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Adds a coupon to an existing basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `CouponItem`. _Example: CouponCodePost_ ``` { "code": "10_percent_off" } ``` #### Responses * **200** Success, the response body contains the basket with the added coupon. Media type: `application/json`. Schema: `Basket`. _Example: CouponCodePost_ ``` { "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 }, { "code": "10_percent_off", "couponItemId": "9372d0f511dac8caf77afc4kj2", "statusCode": "applied", "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 customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). * the coupon number is not provided. * the coupon code specified is invalid. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Remove a coupon from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/coupons/{couponItemId}` Operation ID: `removeCouponFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a coupon from the basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `couponItemId` (path, CouponItemId, required) The ID of the coupon item. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** Success, the response body contains the basket without the deleted coupon. Media type: `application/json`. Schema: `Basket`. _Example Basket: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** Possible reasons: * the basket with the given basket ID is unknown. * the couponItemId URL parameter does not match any coupon item ID in the basket. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Add shopper information to a basket. `PUT /organizations/{organizationId}/baskets/{basketId}/customer` Operation ID: `updateCustomerForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Sets customer information for an existing basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `CustomerInfo`. _Example: BillingAddressPut_ ``` { "email": "shopperUpdate@salesforce-test.com" } ``` #### Responses * **200** Success, the response body contains the basket with the added customer information. Media type: `application/json`. Schema: `Basket`. _Example: BillingAddress_ ``` { "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": "shopperUpdate@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 customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). * the customer cannot be set to the basket because the max number of baskets per customer would be exceeded. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** Possible reasons: * the customer with the given customer number is unknown. * the basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Add a gift certificate to a basket. `POST /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items` Operation ID: `addGiftCertificateItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Adds a gift certificate item to an existing basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 Media type: `application/json`. Schema: `GiftCertificateItem`. _Example: GiftCertificateItemPost_ ``` { "amount": 1, "recipientEmail": "miller@salesforce-test.com", "shipmentId": "me" } ``` #### Responses * **200** Success, the response body contains the basket with the added gift certificate. Media type: `application/json`. Schema: `Basket`. _Example: GiftCertPost_ ``` { "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": "shopperUpdate@salesforce-test.com" }, "giftCertificateItems": [ { "amount": 2, "giftCertificateItemId": "83726a8351540534af93f3b15f", "recipientEmail": "miller@salesforce-test.com", "shipmentId": "me" } ], "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** The gift certificate item amount is negative. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** Possible reasons: * the basket with the given basket ID is unknown. * the shipment with the given shipment ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Remove a gift certificate from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}` Operation ID: `removeGiftCertificateItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Deletes a gift certificate item from an existing basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** Success, the response body contains the basket without the deleted gift certificate. Media type: `application/json`. Schema: `Basket`. * **404** Possible reasons: * the basket with the given basket ID is unknown. * the gift certificate item with the given gift certificate item ID is unknown. ### PATCH Update gift certificate information for a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}` Operation ID: `updateGiftCertificateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates a gift certificate item of an existing basket. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 Media type: `application/json`. Schema: `GiftCertificateItem`. _Example: GiftCertificateItemPost_ ``` { "amount": 1, "recipientEmail": "miller@salesforce-test.com" } ``` #### Responses * **200** Success, the response body contains the basket with the updated gift certificate. Media type: `application/json`. Schema: `Basket`. _Example: GiftCertPatch_ ``` { "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": "shopperUpdate@salesforce-test.com" }, "giftCertificateItems": [ { "amount": 1, "giftCertificateItemId": "83726a8351540534af93f3b15f", "recipientEmail": "miller@salesforce-test.com", "shipmentId": "me" } ], "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** The gift certificate item amount is negative. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** Possible reasons: * the basket with the given basket ID is unknown. * the gift certificate item with the given gift certificate item ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Add an item to a basket. `POST /organizations/{organizationId}/baskets/{basketId}/items` Operation ID: `addItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are: * productId: a valid product ID. This is the ID of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference. * shipmentId: a valid shipment ID (optional). This is the ID of the shipment in which the product item is created. * quantity: a number between 0.01 and 999. This is the quantity of the product to order. * inventoryId: a valid inventory ID (optional). This is the ID of the inventory from which the item is allocated. * bonusDiscountLineItemId: a valid bonus discount line item ID (optional). This is the ID of the bonus discount line item for which the added product is a selected bonus product. * optionItems/optionValueId: a valid option value ID. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the optionItems property. These option items must contain optionId and optionValueId. Also, the values you specify must be valid for the option product that this product item represents. Otherwise, the server throws an InvalidProductOptionItemException or an InvalidProductOptionValueItemException. * custom properties in the form c\_: the custom property must correspond to a custom attribute () defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `array of BasketProductItem`. Array of `BasketProductItem`. _Example: ItemPost_ ``` [ { "productId": "green-bag", "quantity": 1 } ] ``` #### Responses * **200** Success, the response body contains the basket with the added items. Media type: `application/json`. Schema: `Basket`. _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** Possible reasons: * the given product ID is null or invalid. * the product with the given product ID is unknown, offline or not assigned to site catalog or the given product item quantity is null or invalid. * a null quantity value. * the requested product quantity is not available. * the product cannot be added to the basket because of its type. * an option with the specified option ID is unknown. * an option with the specified option value ID is unknown. * the maximum allowed number of products added to the basket, has been exceeded. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). * the provided bonus discount line item ID is not present in the current basket. * the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select. * the selected bonus product is not an applicable product for the bonus discount line item provided. body: application/problem+json: type: ErrorResponse examples: dataTypes.ErrorResponse: !include exchange\_modules/893f605e-10e2-423a-bdb4-f952f56eb6d8/checkout-data-types/2.0.6/examples/errors/bad-request-example.raml * **404** Possible reasons: * the basket with the given basket ID is unknown. * the basket does not contain a shipment with the given shipment ID. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update a basket item. `PATCH /organizations/{organizationId}/baskets/{basketId}/items` Operation ID: `updateItemsInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates multiple items in a basket. This behaviour matches that of updating a single item, but the body contains an array of ProductItems to be updated that are identified by `itemId`. The items to update can include bundled product items, although the kind of update supported for bundled product items is limited to `productId`, `gift`, `giftMessage` and custom properties. The following values in the request body are considered by the server: * `itemId` (mandatory): identifies an item to be updated. * `productId`: a valid product ID. The purpose of this value is to change the variation of a variation product. * `shipmentId`: a valid shipment ID. The purpose of this value is to move a product item to another shipment. * `quantity`: a number between 0 and 999. The purpose of this value is to change the quantity of the product item. If the quantity is 0, the product item is removed. * `optionItems`/`optionValueId`: a valid option value ID. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values, a collection of the option items to be changed must be provided in the property `optionItems`. Those `optionItems` must contain `optionId` and `optionValueId`. The provided values must be valid for the option product that this product item represents. Otherwise, `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` is thrown. * custom properties `c_`: a value corresponding to the type defined for custom attribute `` of the ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for the ProductLineItem. * `gift`: a boolean value that specifies whether the item is a gift. * `giftMessage`: a message to include with the gift. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `array of BasketProductItem`. Array of `BasketProductItem`. _Example: ItemPatch_ ``` { "quantity": 1 } ``` #### Responses * **200** Success, the response body contains the basket with the updated item. Media type: `application/json`. Schema: `Basket`. _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** Possible reasons: * no product item with a given item ID was found for the basket. * the product with the given product ID in the request body is invalid. * a null quantity value. * an option with a specified option ID is unknown. * an option with a specified option value ID is unknown. * the given shipment ID is invalid. * the customer assigned to the basket does not match the verified customer represented by the JWT token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** Possible reasons: basket not found ### DELETE Remove an item from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/items/{itemId}` Operation ID: `removeItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a product item from the basket. #### Parameters * `itemId` (path, ItemId, required) The ID of the item to be updated. * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** Success, the response body contains the basket without the deleted item. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update an item in a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}/items/{itemId}` Operation ID: `updateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates an item in a basket. The item to be updated can be a bundled product item, although the kind of update supported for bundled product items is limited to `productId` (to support variation products), `gift`, `giftMessage` and custom properties. The following values in the request body are considered by the server: * `productId`: a valid product ID. The purpose of this value is to exchange a variation of a variation product. * `shipmentId`: a valid shipment ID. The purpose of this value is to move a product item to another shipment. * `quantity`: a number between 0 and 999. The purpose of this value is to change quantity of the product item. If quantity is 0, the product item is removed. * `optionItems`/`optionValueId`: a valid option value ID. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values a collection of option items to be changed need to be provided in property optionItems. Those optionItems need to contain optionId and `optionValueId`. The provided values must be valid for the option product that this product item represents. Otherwise, `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` is thrown. * custom properties `c_`: a value corresponding to the type defined for custom attribute `` of ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for ProductLineItem. * `gift`: a boolean value that specifies whether the item is a gift * `giftMessage`: a message for the gift #### Parameters * `itemId` (path, ItemId, required) The ID of the item to be updated. * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `BasketProductItem`. _Example: ItemPatch_ ``` { "quantity": 1 } ``` #### Responses * **200** Success, the response body contains the basket with the updated item. Media type: `application/json`. Schema: `Basket`. _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** Possible reasons: * no product item with given item ID was found for the basket. * the product with the given product ID in the request body is invalid. * a null quantity value. * an option with the specified option id is unknown. * an option with the specified option value id is unknown. * the given shipment ID is invalid. * the customer assigned to the basket does not. match the verified customer represented by the JWT token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** Possible reasons: * the basket with the given basket ID is unknown. * a shipment with it's given ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Add taxation information for a basket item. `PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes` Operation ID: `addTaxesForBasketItem`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw). This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for a specific taxable line item. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `itemId` (path, ItemId, required) The ID of the item to be updated. * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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: `TaxItems`. _Example: BasketItemTaxPut_ ``` { "taxItems": [ { "id": "DE_7", "rate": 0.07, "value": 13.99 }, { "id": "DE_19", "rate": 0.19 } ] } ``` #### Responses * **204** Success, without body. * **404** Possible reasons: * The basket with the given basket ID is unknown. * The item with the given item ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` * **409** Possible Reasons: * The tax mode of the referenced basket is not set to EXTERNAL. * One or more tax item custom attributes are invalid. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnsupportedRequest_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-request-if-scapi-hooks-enabled", "title": "Unsupported Request If SCAPI Hooks Enabled", "detail": "You can't call this endpoint because Salesforce Commerce API hook execution is enabled." } ``` ### POST Add a payment instrument to a basket. `POST /organizations/{organizationId}/baskets/{basketId}/payment-instruments` Operation ID: `addPaymentInstrumentToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Adds a payment instrument to a basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `BasketPaymentInstrumentRequest`. _Example: PaymentInstrumentPost_ ``` { "amount": 1, "paymentCard": { "expirationYear": 1990, "expirationMonth": 7, "validFromMonth": 8, "validFromYear": 2007, "issueNumber": "i117", "maskedNumber": "*********1234", "holder": "Miller", "cardType": "Visa" }, "paymentMethodId": "CREDIT_CARD" } ``` _Example: PaymentInstrumentPostWithSalesforcePayments_ ``` { "amount": 15, "paymentMethodId": "Salesforce Payments", "paymentReferenceRequest": { "paymentMethodType": "paypal", "zoneId": "Amer-Zone", "gatewayProperties": { "paypal": { "shippingPreference": "SET_PROVIDED_ADDRESS" } } } } ``` #### Responses * **200** Success, the response body contains the basket with the added payment instrument. Media type: `application/json`. Schema: `Basket`. _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** Possible reasons: * the provided payment method is invalid or not applicable. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Remove a payment instrument from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}` Operation ID: `removePaymentInstrumentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a payment instrument of a basket. #### Parameters * `paymentInstrumentId` (path, PaymentInstrumentId, required) * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** Success, the response body contains the basket without the deleted payment instrument. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** Possible reasons: * the basket with the given basket ID is unknown. * the payment instrument with the given basket payment instrument ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update a payment instrument for a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}` Operation ID: `updatePaymentInstrumentInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates payment instrument of an existing basket. #### Parameters * `paymentInstrumentId` (path, PaymentInstrumentId, required) * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `BasketPaymentInstrumentRequest`. _Example: PaymentInstrumentPatch_ ``` { "amount": 0, "paymentCard": { "holder": "Miller", "cardType": "Visa" }, "paymentMethodId": "CREDIT_CARD" } ``` #### Responses * **200** Success, the response body contains the basket with the updated payment instrument. Media type: `application/json`. Schema: `Basket`. _Example: PaymentInstrumentPatch_ ``` { "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, "holder": "Miller" }, "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 basket payment intsrument with the given id is already permanently masked. * The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** Possible reasons: * the basket with the given basket ID is unknown. * the payment instrument item with the given payment instrument ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### GET Retrieve payment instruments for a basket. `GET /organizations/{organizationId}/baskets/{basketId}/payment-methods` Operation ID: `getPaymentMethodsForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Gets applicable payment methods for an existing basket considering the open payment amount only. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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`. * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success, the response body contains the applicable payment methods for the basket. Media type: `application/json`. Schema: `PaymentMethodResult`. _Example: PaymentMethodsGet_ ``` { "applicablePaymentMethods": [ { "id": "GIFT_CERTIFICATE", "name": "Gift Certificate", "paymentProcessorId": "BASIC_GIFT_CERTIFICATE" }, { "cards": [ { "cardType": "Visa", "checksumVerificationEnabled": true, "name": "Visa", "numberLengths": [ "13", "16" ], "numberPrefixes": [ "4" ] }, { "cardType": "Amex", "checksumVerificationEnabled": true, "name": "American Express", "numberLengths": [ "15" ], "numberPrefixes": [ "34", "37" ] }, { "cardType": "Master Card", "checksumVerificationEnabled": true, "name": "MasterCard", "numberLengths": [ "16" ], "numberPrefixes": [ "51-55" ] }, { "cardType": "Discover", "checksumVerificationEnabled": true, "name": "Discover", "numberLengths": [ "16" ], "numberPrefixes": [ "6011", "622126-622925", "644-649", "65" ] } ], "id": "CREDIT_CARD", "name": "Credit Card", "paymentProcessorId": "BASIC_CREDIT" }, { "id": "PayPal", "name": "Pay Pal", "paymentProcessorId": "PAYPAL_EXPRESS" }, { "id": "BML", "name": "Bill Me Later", "paymentProcessorId": "CYBERSOURCE_BML" } ] } ``` * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Add a price adjustment to a basket. `POST /organizations/{organizationId}/baskets/{basketId}/price-adjustments` Operation ID: `addPriceAdjustmentToBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Adds a custom manual price adjustment to the basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` #### Request body (required) Media type: `application/json`. Schema: `PriceAdjustmentRequest`. _Example: PriceAdjustmentPost_ ``` { "discount": { "value": 5, "type": "percentage" }, "itemText": "MyOrderAdjustment", "level": "order", "promotionId": "manual adjustment" } ``` #### Responses * **200** Success, the response body contains the basket with added price adjustment. Media type: `application/json`. Schema: `Basket`. _Example: PriceAdjustmentPost_ ``` { "adjustedMerchandizeTotalTax": 28.45, "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, "orderPriceAdjustments": [ { "appliedDiscount": { "amount": 0.05, "percentage": 5, "type": "percentage" }, "createdBy": "testAgent", "creationDate": "2015-05-25T09:13:10.942Z", "custom": true, "itemText": "MyOrderAdjustment", "manual": true, "price": -30, "promotionId": "manual adjustment", "priceAdjustmentId": "cdzoAiWbOmbiUaaadlfSpMDgNw" } ], "orderTotal": 615.21, "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": 569.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": 569.97, "shipments": [ { "adjustedMerchandizeTotalTax": 30, "adjustedShippingTotalTax": 0.8, "gift": false, "merchandizeTotalTax": 30, "productSubTotal": 599.97, "productTotal": 569.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: * a fixed price adjustment was already created for the given level. * a fixed price adjustment was added at `order` level. * a promotion ID was used twice. * a system promotion ID was used as a manual promotion ID. * more than one hundred price adjustments would have been created. * the price adjustment limit had exceeded. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Remove a price adjustment from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}` Operation ID: `removePriceAdjustmentFromBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a custom manual price adjustment from the basket. #### Parameters * `priceAdjustmentId` (path, PriceAdjustmentId, required) * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` #### Responses * **200** Success, the response body contains the basket without the deleted price adjustment. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** The priceAdjustmentId is missing, empty or whitespace. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update a price adjustment for a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}` Operation ID: `updatePriceAdjustmentInBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates a custom manual price adjustment on the basket. Only the following path values are considered for the update; all other attributes are ignored. * `discount` * `itemText` * `reasonCode` * `custom properties` The discount `type` of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type `percentage`, the `percentage` attribute is mandatory. For adjustments of type `amount` and `fixed_price`, the `amount` attribute is mandatory. #### Parameters * `priceAdjustmentId` (path, PriceAdjustmentId, required) * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `PriceAdjustment`. _Example: PriceAdjustmentPatch_ ``` { "appliedDiscount": { "amount": 15, "type": "amount" }, "itemText": "AgentOrderAdjustment", "reasonCode": "override manual promo" } ``` #### Responses * **200** Success, the response body contains the basket with the updated price adjustment. Media type: `application/json`. Schema: `Basket`. _Example: PriceAdjustmentPatch_ ``` { "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, "orderPriceAdjustments": [ { "appliedDiscount": { "amount": 15, "type": "amount" }, "createdBy": "testWapiAgent", "creationDate": "2017-03-14T09:15:35.543Z", "custom": true, "itemText": "MyOrderAdjustment", "lastModified": "2017-03-14T09:15:35.594Z", "manual": true, "price": -15, "priceAdjustmentId": "e397cd21f9a9c0643277ba1011", "promotionId": "manual adjustment", "reasonCode": "override manual promo" } ], "orderTotal": 631.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 price adjustment is not manual and cannot be updated. * the expected attributes are missing in the input. * the type of a price adjustment does not match the adjustment type of the input data. * the price adjustment limit is exceeded. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The price adjustment ID is not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: PriceAdjustmentIdNotFoundException_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-adjustment-not-found", "title": "Price Adjustment Not Found", "detail": "No price adjustment with ID '453599643347eac5e4ebd85b49' could be found." } ``` ### GET Retrieve price books for a basket. `GET /organizations/{organizationId}/baskets/{basketId}/price-books` Operation ID: `getPriceBooksForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw). ( DEPRECATED ) Gets applicable price books for an existing basket. This endpoint is deprecated. Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#getApplicablePriceBooks()` instead. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success, the response body contains the priceBookIds for the basket. Media type: `application/json`. Schema: `PriceBookIds`. _Example: PriceBooksGet_ ``` [ "price-book-id1", "price-book-id2" ] ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Add price books to a basket. `PUT /organizations/{organizationId}/baskets/{basketId}/price-books` Operation ID: `addPriceBooksToBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw). ( DEPRECATED ) This method allows you to put an array of priceBookIds to an existing basket, which will be used for basket calculation. This endpoint is deprecated. Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#setApplicablePriceBooks()` instead. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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: `PriceBookIds`. _Example: PriceBooksPut_ ``` [ "price-book-id1", "price-book-id2" ] ``` #### Responses * **204** Success, without body. * **404** The basket with the given basket ID is unknown or contains a price book ID that does not correspond to an existing price book. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### POST Create a shipment for a basket. `POST /organizations/{organizationId}/baskets/{basketId}/shipments` Operation ID: `createShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Creates a new shipment for a basket. The created shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified: * the ID * the shipping address * the shipping method * gift boolean flag * gift message * custom properties #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `Shipment`. _Example: ShipmentsPost_ ``` { "shipmentId": "me2", "shippingMethod": { "id": "001" }, "shippingAddress": { "firstName": "Stephanie", "lastName": "Miller", "address1": "385 Prospect Valley Road", "city": "Woburn", "postalCode": "01801", "stateCode": "MA", "countryCode": "US" } } ``` #### Responses * **200** Success, the response body contains the basket with added shipment. Media type: `application/json`. Schema: `Basket`. _Example: ShipmentsPost_ ``` { "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": "4911 Lincoln Street", "city": "IDANHA", "countryCode": "US", "firstName": "Ward J", "fullName": "Ward J Adamek", "id": "b3e1269a2c1d0ad56694206741", "lastName": "Adamek" }, "shippingMethod": { "description": "Order received in 2 business days", "id": "002", "name": "2-Day Express", "price": 20.99 }, "shippingStatus": "not_shipped", "shippingTotal": 20.99, "shippingTotalTax": 1.05, "taxTotal": 36.05 }, { "adjustedMerchandizeTotalTax": 35, "adjustedShippingTotalTax": 0.8, "gift": false, "merchandizeTotalTax": 35, "productSubTotal": 599.97, "productTotal": 599.97, "shipmentId": "me2", "shipmentTotal": 646.76, "shippingAddress": { "address1": "385 Prospect Valley Road", "city": "Woburn", "stateCode": "MA", "countryCode": "US", "firstName": "Stephanie", "fullName": "Stephanie Miller", "id": "84f06786daa68ae33af7e21ec6", "lastName": "Miller" }, "shippingMethod": { "description": "Order received in 2 business days", "id": "001", "name": "2-Day Express", "price": 15.99 }, "shippingStatus": "not_shipped", "shippingTotal": 15.99, "shippingTotalTax": 0.8, "taxTotal": 35 } ], "shippingItems": [ { "adjustedTax": 1.05, "basePrice": 20.99, "itemId": "d5ed0e58b8f8b5efe8d617a630", "itemText": "Shipping", "price": 20.99, "priceAfterItemDiscount": 20.99, "shipmentId": "me", "tax": 1.05, "taxBasis": 20.99, "taxClassId": "standard", "taxRate": 0.05 }, { "adjustedTax": 0.8, "basePrice": 15.99, "itemId": "6fea9966277c94e06b482a5c43", "itemText": "Shipping", "price": 15.99, "priceAfterItemDiscount": 15.99, "shipmentId": "me", "tax": 0.8, "taxBasis": 15.99, "taxClassId": "standard", "taxRate": 0.05 } ], "shippingTotal": 36.98, "shippingTotalTax": 1.35, "taxation": "net", "taxTotal": 36.35 } ``` * **400** Possible reasons: * a shipment id is not provided. * a shipment with the provided ID already. exists for the basket. * a shipment with the provided shipment number already exists for the basket. * a shipping method with an ID was specified which is not a valid shipping method ID. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### DELETE Remove a shipment from a basket. `DELETE /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}` Operation ID: `removeShipmentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Removes a specified shipment and all associated product, gift certificate, shipping, and price adjustment line items from a basket. It is not allowed to remove the default shipment. #### Parameters * `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified. * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. #### Responses * **200** Success, the response body contains the basket without the deleted shipment. Media type: `application/json`. Schema: `Basket`. _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._ * **400** Possible reasons: * the given shipment ID is invalid. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **403** The given shipment ID corresponds to the default shipment and cannot be removed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BadRequest_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "The shipment with ID 'me' corresponds to the default shipment and can't be deleted." } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PATCH Update a shipment for a basket. `PATCH /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}` Operation ID: `updateShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Updates a shipment for a basket. The shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified: * the ID * the shipping address * the shipping method * gift boolean flag * gift message * custom properties #### Parameters * `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified. * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `Shipment`. _Example: ShipmentsPatch_ ``` { "shipmentId": "me", "shipmentNo": "ignored shipment no", "shippingMethod": { "id": "003" }, "shippingAddress": { "firstName": "Ward J", "lastName": "Adamek", "address1": "4911 Lincoln Street", "city": "IDANHA", "postalCode": "97350", "stateCode": "OR", "countryCode": "US" }, "c_wapi-string": "shipment_custom_property" } ``` #### Responses * **200** Success, the response body contains the basket with the updated shipment. Media type: `application/json`. Schema: `Basket`. _Example: ShipmentsPatch_ ``` { "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": "4911 Lincoln Street", "city": "IDANHA", "countryCode": "US", "firstName": "Ward J", "fullName": "Ward J Adamek", "id": "b3e1269a2c1d0ad56694206741", "lastName": "Adamek" }, "shippingMethod": { "description": "Order received in 2 business days", "id": "002", "name": "2-Day Express", "price": 20.99 }, "shippingStatus": "not_shipped", "shippingTotal": 20.99, "shippingTotalTax": 1.05, "taxTotal": 36.05 } ], "shippingItems": [ { "adjustedTax": 1.05, "basePrice": 20.99, "itemId": "d5ed0e58b8f8b5efe8d617a630", "itemText": "Shipping", "price": 20.99, "priceAfterItemDiscount": 20.99, "shipmentId": "me", "tax": 1.05, "taxBasis": 20.99, "taxClassId": "standard", "taxRate": 0.05 } ], "shippingTotal": 20.99, "shippingTotalTax": 1.05, "taxation": "net", "taxTotal": 36.05 } ``` * **400** Possible reasons: * the given shipment ID was invalid. * a shipment with the provided ID already exists for the basket. * a shipment with the provided shipment number already exists for the basket. * a missing shipping method. * an invalid shipping method. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Update the shipping address for a shipment. `PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-address` Operation ID: `updateShippingAddressForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Sets a shipping address of a specific shipment of a basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified. * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `useAsBilling` (query, boolean) When true, the address is also used as the billing address. * `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values. Default: `true`. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `OrderAddress`. _Example: ShipmentsAddressPut_ ``` { "firstName": "Ward J", "lastName": "Adamek", "address1": "4911 Lincoln Street", "city": "IDANHA", "postalCode": "97350", "stateCode": "OR", "countryCode": "US" } ``` #### Responses * **200** Success, the response body contains the basket with the added shipping address. Media type: `application/json`. Schema: `Basket`. _Example: ShipmentsAddressPut_ ``` { "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": "4911 Lincoln Street", "postalCode": "97350", "city": "IDANHA", "countryCode": "US", "firstName": "Ward J", "fullName": "Ward J Adamek", "id": "b3e1269a2c1d0ad56694206741", "lastName": "Adamek", "stateCode": "OR" }, "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 shipment with the given shipment ID is unknown. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Update the shipping method for a shipment. `PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-method` Operation ID: `updateShippingMethodForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Sets a shipping method to a specific shipment of a basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified. * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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: `ShippingMethod`. _Example: ShipmentsMethodPut_ ``` { "id": "003" } ``` #### Responses * **200** Success, the response body contains the basket with the added shipping method. Media type: `application/json`. Schema: `Basket`. _Example: ShipmentsMethodPut_ ``` { "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": "4911 Lincoln Street", "postalCode": "97350", "city": "IDANHA", "countryCode": "US", "firstName": "Ward J", "fullName": "Ward J Adamek", "id": "b3e1269a2c1d0ad56694206741", "lastName": "Adamek", "stateCode": "OR" }, "shippingMethod": { "description": "Order received the next business day", "id": "003", "name": "Overnight", "price": 29.99 }, "shippingStatus": "not_shipped", "shippingTotal": 29.99, "shippingTotalTax": 1.5, "taxTotal": 36.5 } ], "shippingItems": [ { "adjustedTax": 1.5, "basePrice": 29.99, "itemId": "d5ed0e58b8f8b5efe8d617a630", "itemText": "Shipping", "price": 29.99, "priceAfterItemDiscount": 29.99, "shipmentId": "me", "tax": 1.5, "taxBasis": 29.99, "taxClassId": "standard", "taxRate": 0.05 } ], "shippingTotal": 29.99, "shippingTotalTax": 1.5, "taxation": "net", "taxTotal": 36.5 } ``` * **400** Possible reasons: * the id of the shipping method is missing. * a shipping method with an ID was specified which is not a valid shipping method ID. * the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### GET Retrieve the shipping methods for a shipment. `GET /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-methods` Operation ID: `getShippingMethodsForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Gets the applicable shipping methods for a certain shipment of a basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified. * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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`. * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success, the response body contains the applicable shipping methods for a certain shipment of the basket. Media type: `application/json`. Schema: `ShippingMethodResult`. _Example: ShipmentsMethodGet_ ``` { "applicableShippingMethods": [ { "description": "Order received within 7-10 business days", "id": "001", "name": "Ground", "price": 15.99, "deliveryWindow": { "startAt": "2026-05-04T14:00:00Z", "endAt": "2026-05-07T22:00:00Z" }, "orderCutoffAt": "2026-04-27T14:00:00Z" }, { "description": "Order received in 2 business days", "id": "002", "name": "2-Day Express", "price": 20.99, "deliveryWindow": { "startAt": "2026-04-29T14:00:00Z", "endAt": "2026-04-29T22:00:00Z" }, "orderCutoffAt": "2026-04-27T14:00:00Z" }, { "description": "Order received the next business day", "id": "003", "name": "Overnight", "price": 29.99 }, { "description": "Store Pickup", "id": "005", "name": "Store Pickup", "price": 0, "c_storePickupEnabled": true } ], "defaultShippingMethodId": "001" } ``` * **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomerInfoJwtMismatch_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The customer is invalid." } ``` * **404** Possible reasons: * The basket with the given basket ID is unknown. * The shipment with the given shipment ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### PUT Designate a basket as a storefront basket. `PUT /organizations/{organizationId}/baskets/{basketId}/storefront` Operation ID: `updateAsStorefrontBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Marks a basket as a storefront basket. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `exchange` (query, boolean) If true, an existing storefront basket is exchanged and marked as an agent basket. If false, a `CustomerBasketsQuotaExceededException` is thrown. * `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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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 ``` #### Responses * **200** Success, the response body contains a basket that is set as a storefront basket. Media type: `application/json`. Schema: `Basket`. _Example BasketPutStorefront: same as POST /organizations/{organizationId}/baskets/{basketId}/actions/promote 200 response._ * **400** Returned if a storefront basket already exists and the query parameter `exchange` is false. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CustomerBasketQuotaExceededException: same as POST /organizations/{organizationId}/baskets 400 response._ * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` ### GET Retrieve the external taxation information for a basket. `GET /organizations/{organizationId}/baskets/{basketId}/taxes` Operation ID: `getTaxesFromBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw). This method gives you the external taxation data set by the PUT taxes API. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success, the response body contains the external taxation from all line items from the referenced basket. Media type: `application/json`. Schema: `Taxes`. _Example: PostBasketBody_ ``` { "taxes": { "3d4e28425ce0b3a65b0ac4e163": { "taxItems": [ { "id": "DE_7", "rate": 0.07, "value": 13.99 }, { "id": "DE_19", "rate": 0.19 } ] }, "ff9452ed11fcf5c80f9143a8f1": { "taxItems": [ { "id": "US_1", "rate": 0.01 }, { "id": "US_5", "rate": 0.05 } ] } } } ``` * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` * **409** Possible Reasons: * The tax mode of the referenced basket is not set to EXTERNAL. Media type: `application/json`. Schema: `ErrorResponse`. _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._ _Example: InvalidTaxMode_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-mode", "title": "Invalid Tax Mode", "detail": "Basket with ID 'a10ff320829cb0eef93ca5310a' has invalid tax mode." } ``` ### PUT Add external taxation information to a basket. `PUT /organizations/{organizationId}/baskets/{basketId}/taxes` Operation ID: `addTaxesForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw). This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for all taxable line items. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information. #### Parameters * `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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `basketId` (path, string, required) The ID of the basket to be modified. Minimum length: 1. * `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 ``` * `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: `Taxes`. _Example BasketTaxPut: same as GET /organizations/{organizationId}/baskets/{basketId}/taxes 200 response._ #### Responses * **204** Success, without body. * **404** The basket with the given basket ID is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BasketNotFound_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found", "title": "Basket Not Found", "detail": "No basket with ID '123' could be found." } ``` * **409** Possible Reasons: * The tax mode of the referenced basket is not set to EXTERNAL. * One or more tax item custom attributes are invalid. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._ ## Schemas ### SiteId 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 Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### OrganizationId 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### 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](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### Basket Document representing a basket. * `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only. Example: `4.95`. * `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only. Example: `0.3`. * `agentBasket` (_boolean_) Is the basket created by an agent? It is read only. Example: `true`. * `basketId` (_string_) The unique identifier for the basket. It is read only. Example: `e78aa5646a8efebdd9cdd38be7`. * `billingAddress` (_object_) The billing address. Includes all fields of `OrderAddress`. * `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items. * `channelType` (_string_) The sales channel. It is read only. Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`, `chatgpt`, `gemini`. Example: `storefront`. * `couponItems` (_array of CouponItem_) The coupon items. * `creationDate` (_string (date-time)_) The timestamp when the basket was created. It is read only. Example: `2015-05-19T15:23:18.000Z`. * `currency` (_CurrencyCode_) * `customerInfo` (_object_) The customer information, if the customer is logged in. Includes all fields of `CustomerInfo`. * `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items. * `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only. * `inventoryReservationExpiry` (_string (date-time)_) The expiration datetime of the inventory reservation. It is read only. Example: `2015-05-19T15:30:18.000Z`. * `lastModified` (_string (date-time)_) The timestamp when the basket was last modified. It is read only. Example: `2015-05-19T15:25:18.000Z`. * `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total price represents the sum of the product prices before services (such as shipping) or adjustments from promotions have been added. It is read only. Example: `4.95`. * `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments. * `orderTotal` (_number (double)_) The total price, including products, shipping and tax. It is read only. Example: `110.24`. * `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list. * `productItems` (_array of BasketProductItem_) The product items. * `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `99`. * `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `88`. * `shipments` (_array of Shipment_) The shipments. * `shippingItems` (_array of ShippingItem_) The shipping items. * `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `5.99`. * `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only. Example: `0.3`. * `sourceCode` (_string_) The source code assigned to the basket. It is read only. Example: `OUTDOOR1`. * `taxTotal` (_number (double)_) The total tax amount. It is read only. Example: `5.25`. * `taxation` (_string_) The taxation policy (gross or net). It is read only. Allowed values: `gross`, `net`. Example: `net`. * `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false. Example: `true`. * `temporaryBasket` (_boolean_) If the created basket is a temporary basket, this is set to true. Otherwise, it is set to false. Example: `true`. * `approachingDiscounts` (_array of ApproachingDiscount_) A list of approaching discount objects for the basket. The list includes both order-level and shipping-level promotions. This field is only included when the expand query parameter contains 'approaching\_discounts'. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### OrderAddress Document representing an order address. * `address1` (_string_) The first address line. Example: `45 Main Rd.`. * `address2` (_string_) The second address line. Example: `Apartment 204`. * `city` (_string_) The city. Example: `Boston`. * `companyName` (_string_) The company name. Example: `Salesforce`. * `countryCode` (_CountryCode_) * `firstName` (_string_) The first name. Example: `Max`. * `fullName` (_string_) The full name. Example: `Max Mustermann`. * `id` (_string_) The ID of the address. Example: `me`. * `jobTitle` (_string_) The job title. Example: `Software Engineer`. * `lastName` (_string_) The last name. Example: `Mustermann`. * `phone` (_string_) The phone number. Example: `6175555555`. * `postBox` (_string_) The post office box. Example: `PO BOX 109`. * `postalCode` (_string_) The postal code. Example: `05408`. * `salutation` (_string_) The salutation. Example: `Mr`. * `secondName` (_string_) The second name. * `stateCode` (_string_) The state code. Example: `MA`. * `suffix` (_string_) The suffix. Example: `Sr`. * `suite` (_string_) The suite. Example: `24A`. * `title` (_string_) The title. Example: `Dr.`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### CouponItem Document representing a coupon item. * `code` (_string_, required) The coupon code. Maximum length: 256. Example: `5ties`. * `couponItemId` (_object_) The coupon item ID. It is read only. Includes all fields of `CouponItemId`. * `statusCode` (_string_) The status of the coupon item. It is read only. Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`. * `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion". It is read only. Example: `true`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### CouponItemId The coupon item ID Type: `string`. Minimum length: 1. Example: `d4c9c0141e9c74c150225580f3`. ### CustomerInfo The customer information for guest or logged-in customers. * `customerId` (_string_) The customer ID. It is read only. Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`. * `customerName` (_string_) The customer name. Example: `Max Mustermann`. * `customerNo` (_string_) The customer number. Maximum length: 100. Example: `0002352`. * `email` (_string_, required) The customer's email address. Example: `no-reply@salesforce.com`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### GiftCertificateItem A gift certificate item. * `amount` (_number (double)_, required) The gift certificate item amount. Example: `20`. * `giftCertificateItemId` (_object_) The item ID. It is read only. Includes all fields of `GiftCertificateItemId`. * `message` (_string_) The gift certificate message. Maximum length: 4000. Example: `Birthday present.`. * `recipientEmail` (_string_, required) The recipient email. Minimum length: 1. Example: `no-reply@salesforce.com`. * `recipientName` (_string_) The recipient's name. Example: `Daniel Mustermann`. * `senderName` (_string_) The sender's name. Example: `Max Mustermann`. * `shipmentId` (_string_) The ID of the shipment this item belongs to. Example: `me`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### GiftCertificateItemId Type: `string`. Minimum length: 1. Example: `629dea6e7b61e58da629b57b21`. ### BasketProductItem Document representing a basket product item. Includes all fields of `ProductItem`. ### ItemId The item id. Type: `string`. Example: `430ef5aad3a24de59378458434`. ### TaxItems Taxation for a line item. * `taxItems` (_array of TaxItem_) The list of tax items. It is read only. ### BasketPaymentInstrumentRequest Document representing a basket payment instrument request. * `amount` (_number (double)_) The payment transaction amount. Example: `130.88`. * `bankRoutingNumber` (_string_) The bank routing number. Maximum length: 256. Example: `12030000`. * `giftCertificateCode` (_string_) The gift certificate code. Maximum length: 256. Example: `AFGRTUZ`. * `paymentCard` (_object_) The payment card. Includes all fields of `OrderPaymentCardRequest`. * `giftCardRequest` (_object_) The gift card request. Includes all fields of `GiftCardRequest`. * `paymentMethodId` (_string_) The payment method ID. Maximum length: 256. Example: `CREDIT_CARD`. * `paymentReferenceRequest` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled. Includes all fields of `PaymentReferenceRequest`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PaymentInstrumentId The payment instrument ID Type: `string`. Example: `ba248424e3eee797f062162f8b`. ### PaymentMethodResult Result document of payment methods applicable for a basket. * `applicablePaymentMethods` (_array of PaymentMethod_) The applicable payment methods. It is read only. ### PriceAdjustmentRequest Request that represents a price adjustment. * `discount` (_object_) A discount that can be specified instead of a price. Includes all fields of `DiscountRequest`. * `itemId` (_string_) The item to which the price adjustment should be added, depending on the specified level. If the level is ´order´, item id is not needed. If `shipping`, specify the UUID of the shipping item. If `product`, specify the UUID of the product item. Example: `93196fae953cbedbe54d67e760`. * `itemText` (_string_) The text describing the item in more detail. Example: `A discounted item`. * `level` (_string_, required) The level at which the adjustment is applied. * `order` indicates that the price adjustment should be added directly to basket. * `product` indicates that the price adjustment should be added to the product item. * `shipping` indicates that the price adjustment is added to the shipping item. Allowed values: `product`, `shipping`, `order`. Example: `order`. * `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID as long as it's not used by a price adjustment belonging to the same item and isn't used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated. Example: `Shipping100`. * `reasonCode` (_string_) The reason for the price adjustment. Example: `Shipping promotion on order above $1,000 USD`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PriceAdjustmentId Type: `string`. Example: `ba248424e3eee797f062161f8b`. ### PriceAdjustment Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level. * `appliedDiscount` (_object_) Details describing the discount this price adjustment is based on. For adjustments not based on a discount, this value is null. Includes all fields of `Discount`. * `couponCode` (_string_) The coupon code of the coupon this price adjustment is based on. For adjustments not based on a coupon, this value is null. It is read only. Example: `5ties`. * `createdBy` (_string_) The user who created the price adjustment. It is read only. Example: `Support`. * `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created. It is read only. Example: `2015-05-19T15:23:18.000Z`. * `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine. Example: `true`. * `itemText` (_string_) The text describing the item. * `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified. It is read only. Example: `2021-02-25T09:58:08.715Z`. * `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false. Example: `true`. * `price` (_number (double)_) The adjustment price. It is read only. Example: `120.88`. * `priceAdjustmentId` (_object_) The price adjustment ID. It is read only. Includes all fields of `PriceAdjustmentId`. * `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID so long it is not used by a price adjustment belonging to the same item, and is not used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated. * `reasonCode` (_string_) The reason for the price adjustment. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PriceBookIds Array of price book IDs to use for the basket calculation. Array of `string`. Items: Maximum length: 256. Maximum items: 10. ### Shipment Document representing a shipment. * `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only. Example: `4.95`. * `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only. Example: `0.3`. * `deliveryWindow` (_object_) The estimated delivery window for the shipment. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a delivery window. This field is reserved for future use and will be supported in an upcoming release. Includes all fields of `DeliveryWindow`. * `gift` (_boolean_) A flag indicating whether the shipment is a gift. It is read only. Example: `true`. * `giftMessage` (_string_) The gift message. Example: `Happy Birthday`. * `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping. It is read only. Example: `4.95`. * `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a cutoff time. This field is reserved for future use and will be supported in an upcoming release. Example: `2026-04-27T14:00:00Z`. * `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `99`. * `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `99`. * `shipmentId` (_object_) The order-specific ID of the shipment. The default value is 'me'. Default: `me`. Includes all fields of `ShipmentId`. Default: `me`. * `shipmentNo` (_string_) The shipment number of this shipment. This number is automatically generated. It is read only. * `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax. It is read only. Example: `39.99`. * `shippingAddress` (_object_) The shipping address. Includes all fields of `OrderAddress`. * `shippingMethod` (_ShippingMethod_) * `shippingStatus` (_string_) The shipping status of the shipment. Allowed values: `not_shipped`, `shipped`. Example: `shipped`. * `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `5.99`. * `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments. It is read only. Example: `0.3`. * `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only. Example: `1.8`. * `trackingNumber` (_string_) The tracking number of the shipment. Example: `1Z204E380338943508`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ShipmentId The identifier of the shipment Type: `string`. Minimum length: 1. Example: `me`. ### ShippingMethod Document representing a shipping method. * `deliveryWindow` (_object_) The estimated delivery window for this shipping method. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a delivery window. Includes all fields of `DeliveryWindow`. * `description` (_string_) The localized description of the shipping method. Example: `Order received within 7-10 business days`. * `externalShippingMethod` (_string_) The external shipping method. * `id` (_string_, required) The shipping method ID. Maximum length: 256. Example: `001`. * `name` (_string_) The localized name of the shipping method. Example: `Ground`. * `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a cutoff time. Example: `2026-04-27T14:00:00Z`. * `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only. Example: `15`. * `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ShippingMethodResult Result document containing shipping methods. * `applicableShippingMethods` (_array of ShippingMethod_) The applicable shipping method documents. It is read only. * `defaultShippingMethodId` (_string_) The default shipping method. It is read only. Example: `me`. ### Taxes Document representing the tax rates and (optionally) amounts for all items in a basket. * `taxes` (_object_, required) Map containing the TaxItems for the line item ids: Map Additional properties: `TaxItems`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`. ### BonusDiscountLineItem Document representing a bonus discount line item. * `bonusProducts` (_array of ProductDetailsLink_) The bonus products the customer can choose from. * `couponCode` (_string_) The coupon code that triggered the promotion, if applicable. Example: `5ties`. * `id` (_string_) The ID of the line item. It is read only. Example: `91f4dd8bfa0653d58b7783b04f`. * `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion. * `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item. Example: `Buy1Get2`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### CurrencyCode A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. Type: `string`. Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`. ### GroupedTaxItem Document representing the grouped tax item. * `taxRate` (_number (double)_) The tax rate. It is read only. Example: `0.1`. * `taxValue` (_number (double)_) The summed up tax total for the tax rate. It is read only. Example: `10.03`. ### OrderPaymentInstrument Document representing an order payment instrument. * `amount` (_number (double)_) The payment transaction amount. Example: `130.88`. * `authorizationStatus` (_object_) The authorization status of the payment transaction. It is read only. Includes all fields of `Status`. * `bankRoutingNumber` (_string_) The bank routing number. Maximum length: 256. Example: `12030000`. * `fraudDecisions` (_object_) The normalized fraud decisions for the order payment instrument. It is read only. Omitted when no decisions are returned. Includes all fields of `FraudDecisions`. * `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked. Example: `******Gzzy`. * `paymentCard` (_object_) The payment card. Includes all fields of `PaymentCard`. * `paymentDetails` (_object_) The normalized, shopper-relevant payment details for the order payment instrument. It is read only. Omitted when no details are available for the payment. Includes all fields of `PaymentDetails`. * `giftCard` (_object_) The gift card. Includes all fields of `GiftCardResponse`. * `paymentInstrumentId` (_object_) The payment instrument ID. It is read only. Includes all fields of `PaymentInstrumentId`. * `paymentMethodId` (_string_) The payment method ID. It is read only. Maximum length: 256. Example: `CREDIT_CARD`. * `paymentReference` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled. * `paymentReferenceId` (_string_) Payment reference identifier. Can be payment intent ID for Stripe, PSP reference for Adyen, PayPal order ID for PayPal, or similar identifier for other payment providers. Maximum length: 256. Example: `pi_3N4B2vF0wDjebNCp1234567`. * `gateway` (_string_) The payment gateway used to process the payment. Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`. * `gatewayProperties` (_object_) The payment gateway specific properties. * `stripe` (_object_) ## Stripe specific properties. * setupFutureUsage: Indicates that you intend to make future payments with this payment method. * **on\_session**: The payment method is intended to be used for a future payment on the same website session. * **off\_session**: The payment method is intended to be used for a future payment on a different website session. * **null**: The payment method is not intended to be used for a future payment. * clientSecret: Secret for Stripe client-side payment confirmation. Don't store, log, or expose the client secret to anyone other than the customer, and only use it on pages where TLS is enabled. * type: string * maxLength: 256 * example: "pi\_1J4K5L2eZvKYlo2CyZ8K5L6M\_secret\_abc123" * `paypal` (_object_) ## PayPal specific properties. * `adyen` (_object_) ## Adyen specific properties. * adyenError: Error information returned by Adyen if the payment fails. Null on success. * adyenPaymentIntent: The Adyen payment intent object containing payment details and required actions. * resultCode: The result of the payment request (for example, "REDIRECT\_SHOPPER", "AUTHORISED", "PENDING", "REFUSED"). * accountID: The Adyen merchant account ID. * adyenPaymentIntentAction: The action object for payment methods requiring additional shopper interaction. * url: The URL for completing the payment (redirect or 3DS authentication). * type: The action type (for example, "redirect", "threeDS2", "voucher"). * method: The HTTP method for the action (for example, "GET", "POST"). * successful: A boolean indicating whether the Adyen operation is successful. ### ShippingItem Document representing a shipping item. * `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments. It is read only. Example: `19`. * `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `50`. * `itemId` (_string_) The shipping item ID. Use it to identify this shipping item when updating its quantity or creating a custom price adjustment for it. It is read only. Example: `430ef5aad3a24de59378458434`. * `itemText` (_string_) The text describing the shipping item. Example: `Shipping`. * `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only. * `priceAdjustments` (_array of PriceAdjustment_) The price adjustments. * `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. * `shipmentId` (_object_) The identifier of the shipment to which this item belongs. Includes all fields of `ShipmentId`. * `tax` (_number (double)_) The tax on the product item, not including adjustments. It is read only. Example: `0.19`. * `taxBasis` (_number (double)_) The price used to calculate the tax for this shipping item. It is read only. * `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only. * `taxItems` (_array of TaxItem_) The individual tax items for this shipping line item (e.g. state tax, county tax). It is read only. Maximum items: 10. * `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. It is read only. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ApproachingDiscount Document representing an approaching discount for a basket. Contains information about promotions the customer is close to qualifying for. * `type` (_string_, required) The type of approaching discount (order-level or shipping-level). Allowed values: `order`, `shipping`. Example: `order`. * `conditionThreshold` (_number (double)_) The total amount needed to receive the discount. Example: `100`. * `merchandiseTotal` (_number (double)_) The amount the customer basket contributes towards the purchase condition. Example: `90`. * `discount` (_object_) The applied discount when the order meets the threshold. Includes all fields of `Discount`. * `promotionLink` (_object_) Document representing a promotion link. Includes all fields of `PromotionLink`. * `shipmentId` (_string_) The unique id of the shipment the discount relates to. Only applicable when type = shipping. Minimum length: 1. Maximum length: 256. Example: `me`. * `shippingMethods` (_array of ShippingMethod_) The shipping methods the promotion relates to. Only applicable when type = shipping. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### CountryCode A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard. Type: `string`. Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`. ### ProductItem Document representing a product item. * `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only. Example: `19`. * `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `130`. * `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only. * `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. Example: `true`. * `bundledProductItems` (_array of ProductItem_) The bundled product items. * `gift` (_boolean_) Returns true if the item is a gift. It is read only. Example: `true`. * `giftMessage` (_string_) The gift message. Example: `Happy Birthday`. * `inventoryId` (_string_) The inventory list ID associated with this item. Maximum length: 256. Example: `inventory`. * `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only. Includes all fields of `ItemId`. * `itemText` (_string_) The text describing the item. * `optionItems` (_array of OptionItem_) The option items. * `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only. * `priceAdjustments` (_array of PriceAdjustment_) The price adjustments. * `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `20.99`. * `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `15.5`. * `productId` (_string_) The ID of the product. Maximum length: 100. Example: `nintendo-ds-console`. * `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item. Includes all fields of `ProductListItemReference`. * `productName` (_string_) The name of the product. Example: `Nintendo DS Game Console`. * `qualifyingProductItemId` (_string_) Returns the id of the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with number of qualifying products granting a bonus-product discount. If these conditions aren't met, the method returns null. If there are multiple product line items that triggered this bonus product, this method returns the last one by position within the order. Maximum length: 28. * `quantity` (_number (double)_) The quantity of the products represented by this item. Minimum: 0. Example: `1`. * `shipmentId` (_string_) The ID of the shipment this item belongs to. Example: `me`. * `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only. Example: `006490dcc338feeafc71c964bf`. * `tax` (_number (double)_) The tax for the product item, not including price adjustments. It is read only. Example: `0.3`. * `taxBasis` (_number (double)_) The price used to calculate the tax for this product item. It is read only. Example: `30`. * `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only. * `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax). It is read only. Maximum items: 10. * `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only. Example: `0.9`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### TaxItem Object representing the taxation. * `id` (_string_, required) The taxation identifier. * `rate` (_number (double)_, required) The taxation rate. Example: `0.13`. * `value` (_number (double)_) The tax amount. Will be computed if not set. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### OrderPaymentCardRequest Document representing an order payment card request. * `cardType` (_string_) The payment card type (for example: Visa). Maximum length: 256. Example: `Visa`. * `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store. Example: `E67TY8GQ27X`. * `expirationMonth` (_integer (int32)_) The month when the payment card expires. Example: `3`. * `expirationYear` (_integer (int32)_) The year when the payment card expires. Example: `2025`. * `holder` (_string_) The payment card holder. Maximum length: 256. Example: `Max Mustermann`. * `issueNumber` (_string_) The payment card issue number. Maximum length: 256. Example: `2`. * `maskedNumber` (_string_) The masked payment card number. Maximum length: 25. Pattern: ^\[0-9 -\]{0,7}\\D{6,15}\\d{0,4}$. Example: `*********4422`. * `validFromMonth` (_integer (int32)_) The month the payment card is valid from. Minimum: 1. Maximum: 12. Example: `5`. * `validFromYear` (_integer (int32)_) The year the payment card is valid from. Example: `2019`. ### GiftCardRequest Represents gift card details for a request. * `brand` (_string_, required) The gift card type or brand (for example, givex, blackhawk). Maximum length: 256. Example: `givex`. * `cardNumber` (_string_, required) The gift card number. Maximum length: 40. Example: `6364530000000000`. * `cvc` (_string_, required) The card verification code (CVC/CVV) for the gift card. Maximum length: 4. Example: `123`. * `expirationMonth` (_integer (int32)_) The month when the gift card expires. Example: `1`. * `expirationYear` (_integer (int32)_) The year when the gift card expires. Example: `2030`. ### PaymentReferenceRequest Properties for Payments Reference Request * `paymentMethodType` (_string_) Payment Method Type Maximum length: 64. Example: `card`. * `zoneId` (_string_) The unique identifier for a Payments zone. Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\\-\_\]{1,100}$. _Example_ ``` { "Amer-Zone": null } ``` * `gateway` (_string_) The payment gateway used to process the payment. Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`. * `gatewayProperties` (_object_) The payment gateway specific properties. * `stripe` (_object_) ## Stripe specific properties. * setupFutureUsage: Indicates that you intend to make future payments with this payment method. * **on\_session**: The payment method is intended to be used for a future payment on the same website session. * **off\_session**: The payment method is intended to be used for a future payment on a different website session. * **null**: The payment method is not intended to be used for a future payment. * `paypal` (_object_) ## PayPal specific properties. * shippingPreference: Shipping preference for PayPal payment processing. Applicable only for basket payment instruments. * **GET\_FROM\_FILE** * **NO\_SHIPPING** * **SET\_PROVIDED\_ADDRESS** * `adyen` (_object_) ## Adyen specific properties. ### PaymentMethod Document representing a payment method. * `cards` (_array of PaymentCardSpec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD). It is read only. * `description` (_string_) The localized description of the payment method or card. It is read only. * `id` (_string_, required) The ID of the payment method or card. It is read only. Maximum length: 256. * `image` (_string_) The URL to the image that represents the payment method or card. It is read only. * `name` (_string_) The localized name of the payment method or card. It is read only. * `paymentProcessorId` (_string_) The payment processor ID. It is read only. It is read only. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### DiscountRequest Request that represents a discount to be applied to a custom price adjustment. * `type` (_string_, required) The type of discount. * `amount` describes a (unit) price discount, and its corresponding value (positive) defines the amount each unit is to be reduced by. Example: For a $10 discount, set `type` to `amount` and `value` to `10.00`. * `percentage` describes a percentage discount, and its corresponding value (positive) defines the percentage reduction. Example: For a 5% discount, set `type` to `percentage` and `value` to `5.00`. * `fixed_price` describes a fixed price discount, and its corresponding value (positive) defines the resulting fixed price for the item. Only one `fixed_price` discount can be set for each item. Example: To set a fixed price of $15, set `type` to `fixed_price` and `value` to `15.00`. **Important**: Setting `type` to `fixed_price` is not supported when `level` is set to `order`. Allowed values: `percentage`, `fixed_price`, `amount`. Example: `percentage`. * `value` (_number (double)_, required) The amount of the discount. Example: `20`. ### Discount Document representing a discount. * `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts. It is read only. Example: `130.88`. * `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts. It is read only. Example: `0.19`. * `priceBookId` (_string_) The price book ID that is used with some types. It is read only. Example: `usd-sale-prices`. * `type` (_string_, required) The type of discount. It is read only. Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### DeliveryWindow The range describing when an item is expected to be delivered. Both bounds are RFC 3339 date-time timestamps. The API preserves sub-day precision end-to-end. * `startAt` (_string (date-time)_) The earliest expected delivery time, as an RFC 3339 date-time. Example: `2026-04-30T14:00:00Z`. * `endAt` (_string (date-time)_) The latest expected delivery time, as an RFC 3339 date-time. Example: `2026-04-30T18:00:00Z`. ### ShippingPromotion Document representing a shipping promotion. * `calloutMsg` (_string_) The localized callout message of the promotion. Example: `$30 Fixed Shipping Amount Above 150`. * `promotionId` (_string_) The unique ID of the promotion. Example: `$30FixedShippingAmountAbove150`. * `promotionName` (_string_) The localized promotion name. Example: `$30 Fixed Shipping Amount Above 150`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ProductDetailsLink Document representing a link to the resource for product details. * `productDescription` (_string_) The description of the product. Example: `Nintendo DS revolutionizes handheld gameplay.`. * `productId` (_ProductId_, required) * `productName` (_string_) The name of the product. Example: `Nintendo DS Game Console`. * `title` (_string_) The link title. Example: `Nintendo DS Game Console`. ### Status Document representing an object status. * `code` (_string_) The status code. * `message` (_string_) The status message. * `status` (_integer (int32)_) The status. For more information on the status values see Status.OK and Status.ERROR. ### FraudDecisions Normalized fraud decisions for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no decisions are returned. The values remain readable for historical orders. * `preAuthorization` (_string_) The pre-authorization fraud decision used by the client to orchestrate checkout. Expected values are: * `NOT_REVIEWED`: the payment instrument was not reviewed pre-authorization. * `APPROVED`: the payment authorization can proceed. * `CHALLENGE`: the payment authorization should be challenged with additional verification (for example, a 3D Secure challenge) before it can proceed. * `DECLINED`: the payment authorization is declined. A custom value may also be returned. It is read only. Maximum length: 256. Example: `APPROVED`. ### PaymentCard Document representing a payment card. * `cardType` (_string_) The payment card type. Maximum length: 256. Example: `Visa`. * `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired. It is read only. Example: `true`. * `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store. Example: `E67TY8GQ27X`. * `expirationMonth` (_integer (int32)_) The month when the payment card expires. Example: `3`. * `expirationYear` (_integer (int32)_) The year when the payment card expires. Example: `2025`. * `holder` (_string_) The payment card holder. Maximum length: 256. Example: `Max Mustermann`. * `issueNumber` (_string_) The payment card issue number. Maximum length: 256. Example: `2`. * `maskedNumber` (_string_) The masked payment card number. Maximum length: 4000. Example: `*********4422`. * `numberLastDigits` (_string_) The last digits of the payment card number. It is read only. Maximum length: 4000. Example: `4422`. * `validFromMonth` (_integer (int32)_) The month the payment card is valid from. Minimum: 1. Maximum: 12. Example: `5`. * `validFromYear` (_integer (int32)_) The year the payment card is valid from. Example: `2015`. ### PaymentDetails Normalized, shopper-relevant payment details for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no details are available for the payment. The values remain readable for historical orders. * `type` (_string_) The normalized payment method type. Expected values are `bancontact`, `card`, `gift_card`, `eps`, `ideal`, `klarna`, `sepa_debit`, `paypal`, `venmo`, `afterpay_clearpay`, `amazon_pay`, and `twint`. A custom value may also be returned. It is read only. Maximum length: 256. Example: `card`. * `brand` (_string_) The normalized card brand. Expected values are `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, and `unknown`. A custom value may also be returned. It is read only. Maximum length: 20. Example: `visa`. * `last4` (_string_) The last four digits of the payment instrument. It is read only. Maximum length: 4. Example: `4242`. * `walletType` (_string_) The normalized digital wallet used for the payment. Expected values are `apple_pay` and `google_pay`. A custom value may also be returned. It is read only. Maximum length: 20. Example: `apple_pay`. * `expirationMonth` (_integer (int32)_) The month when the payment instrument expires. It is read only. Minimum: 1. Maximum: 12. Example: `12`. * `expirationYear` (_integer (int32)_) The year when the payment instrument expires. It is read only. Example: `2028`. * `token` (_string_) The reference token representing the payment instrument. This is an opaque identifier, not the card number (PAN). It is read only. Maximum length: 40. Example: `pm_abc123`. * `tokenType` (_string_) The type of token backing the reference token. Expected values are `NETWORK` and `GATEWAY`. A custom value may also be returned. It is read only. Maximum length: 20. Example: `GATEWAY`. * `accountHolderName` (_string_) The name of the payment instrument account holder. It is read only. Maximum length: 256. Example: `Alex Shopper`. ### GiftCardResponse Document representing a gift card response. * `brand` (_string_) The gift card brand. Maximum length: 256. Example: `givex`. * `maskedCardNumber` (_string_) The masked gift card number. Maximum length: 40. Example: `*********4422`. * `expirationMonth` (_integer (int32)_) The month when the gift card expires. Example: `1`. * `expirationYear` (_integer (int32)_) The year when the gift card expires. Example: `2030`. ### PromotionLink Document representing a promotion link. * `promotionId` (_string_) The unique id of the promotion. Minimum length: 1. Maximum length: 256. Example: `10off100`. * `name` (_string_) The localized name of the promotion. Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`. * `calloutMsg` (_string_) The localized call-out message of the promotion. Minimum length: 1. Maximum length: 256. Example: `Spend $10 more to save 10%!`. * `title` (_string_) The link title. Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`. * `link` (_string_) The URL addressing the promotion. Minimum length: 1. Maximum length: 2048. Example: `/s/SiteGenesis/promotion?id=10off100`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### OptionItem An option item represents an optional purchase related to a product item, and is always associated with that parent product item. An option item can have different values from which to select. For example, a refrigerator item can have an option item representing an extended warranty, with a set of option item values representing different warranty lengths. When a shopper purchases the warranty option item together with the parent refrigerator item, they select one of the available warranty option item values. * `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only. Example: `19`. * `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `50`. * `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only. Example: `ba248414e3eee797f062162f8b`. * `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. It is read only. Example: `false`. * `bundledProductItems` (_array of ProductItem_) The bundled product items. * `gift` (_boolean_) Returns true if the item is a gift. It is read only. Example: `false`. * `giftMessage` (_string_) The gift message. Example: `Happy Birthday`. * `inventoryId` (_string_) The inventory list ID associated with this item. It is read only. Maximum length: 256. Example: `inventory`. * `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only. Includes all fields of `ItemId`. * `itemText` (_string_) The text describing the item. Example: `The item text.`. * `optionId` (_string_, required) The ID of the option. It is read only. Maximum length: 256. Example: `consoleWarranty`. * `optionItems` (_array of OptionItem_) The option items. * `optionValueId` (_string_, required) The ID of the option value. It is read only. Maximum length: 256. Example: `000`. * `price` (_number (double)_) The price of the line item before applying any adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `150.99`. * `priceAdjustments` (_array of PriceAdjustment_) The price adjustments. * `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `50.99`. * `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only. Example: `40.5`. * `productId` (_ProductId_) * `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item. Includes all fields of `ProductListItemReference`. * `productName` (_string_) The name of the product. Example: `Nintendo DS Game Console`. * `quantity` (_number (double)_) The ordered quantity of the products represented by this item. Minimum: 0. Example: `1`. * `shipmentId` (_string_) The ID of the shipment this item belongs to. Example: `me`. * `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only. Example: `006490dcc338feeafc71c964bf`. * `tax` (_number (double)_) The tax on the line item before applying any adjustments. It is read only. Example: `0`. * `taxBasis` (_number (double)_) The amount used to calculate the tax for this item. It is read only. Example: `50`. * `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only. * `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only. Example: `0.19`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ProductListItemReference Document representing product list item details. * `id` (_object_, required) The ID of the product list item. It is read only. Includes all fields of `ItemId`. * `priority` (_integer (int32)_) The priority of the product list item. Example: `1`. * `productDetailsLink` (_ProductDetailsLink_) * `productList` (_object_) A reference to the associated product list. It is read only. Includes all fields of `ProductListLink`. * `public` (_boolean_) Example: `false`. * `purchasedQuantity` (_number (double)_) The total quantity of this item purchased from the product list. Example: `0`. * `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item. Minimum: 0. Example: `1`. * `type` (_string_) Specifies whether the item is a product or a gift certificate. Allowed values: `product`, `gift_certificate`. Example: `product`. ### PaymentCardSpec Document representing the specification for a payment card. * `cardType` (_string_) The payment card type. It is read only. Example: `Visa`. * `checksumVerificationEnabled` (_boolean_) A flag indicating whether the card number is verified using the Luhn checksum algorithm. It is read only. Example: `true`. * `description` (_string_) The localized description of the payment card. It is read only. * `image` (_string_) The URL to the image that represents the payment card. It is read only. * `name` (_string_) The localized name of the payment card. It is read only. * `numberLengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges). It is read only. * `numberPrefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges). It is read only. * `securityCodeLength` (_integer (int32)_) The length of the security code for this card. It is read only. ### ProductId The id (SKU) of the product. Type: `string`. Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`. ### ProductListLink Document representing a link to a product list. * `description` (_string_) The description of this product list. * `name` (_string_) The name of this product list. * `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers. It is read only. Example: `true`. * `title` (_string_) The link title. * `type` (_string_) The type of the product list. Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `shopping_list`.