Salesforce Docs Portal

Shop Baskets (deprecated)

POST Create basket

POST /baskets

Operation ID: Create basket. Tags: baskets. Security: customers_auth; oauth2_application; client_id.

Creates a new basket. The created basket is initialized with default values. Data provided in the body document will be populated into the created basket. Query parameter temporary can be set to true to create a temporary basket for the customer. The default value is false . Temporary baskets are separate from shopper storefront and agent baskets, and are intended for use to perform calculations or create an order without disturbing a shopper's open storefront basket. Temporary baskets are automatically deleted after a short time (15 minutes). A temporary basket can be identified with the property temporary_basket , which is true for temporary basket and false otherwise. Temporary baskets are available to all shoppers including guests (unlike agent baskets). All functionality that exists for a basket also applies to a temporary basket.
A basket can be updated with further Shop API calls. Considered values from the request body are:

  • customer information: PUT /baskets/{basket_id}/customer

  • billing address: PUT /baskets/{basket_id}/billing_address

  • shipments including shipping address and shipping method: POST /baskets/{basket_id}/shipments

  • product items: POST /baskets/{basket_id}/items

  • coupon items: POST /baskets/{basket_id}/coupons

  • Invalid coupons are silently ignored.

  • gift certificate items: POST /baskets/{basket_id}/gift_certificates

  • payment method and card type: POST /baskets/{basket_id}/payment_instruments

  • custom properties: PATCH /baskets/{basket_id}

Related resource means with which resource you can specify the same data after the basket creation. Identify the basket using the basket_id property, which should be integrated into the path of an update request, for example a POST to /baskets/{basket_id}/items . The resource supports JWT or OAuth tokens for authentication:

  • A customer must provide a JWT which specifies exactly one customer (it may be a guest or a registered customer). In this case the resource creates a basket for this customer.

  • An agent must provide an OAuth token. The agent can use this resource to create a basket for a newly created guest customer, and can later update the customer if desired.

The number of baskets which can be created per customer is limited. When a basket is created it is said to be open . It remains open until either an order is created from it using a POST to resource /orders or it is deleted using a DELETE to resource /baskets/{basket_id} . The number of open baskets allowed depends on the authentication method used and the type of basket:

  • When using JWT each customer can have just 1 open basket. In addition, each customer can have up to 4 open temporary baskets (by default).

  • When using OAuth each customer can have up to 4 open baskets. These baskets can be temporary baskets or a mix of storefront and temporary baskets.

Custom properties in the form c_ < CUSTOM_NAME > are supported. A custom property must correspond to a custom attribute ( < CUSTOM_NAME > ) defined for the Basket system object, and its value must be valid for that custom attribute. Other basket properties like the channel type or source code cannot be set with this resource.

This endpoint may return the following faults:

  • 400 - CustomerBasketsQuotaExceededException - Thrown if a new basket cannot be created because the maximum number of baskets per customer would be exceeded.
  • 400 - CustomerTemporaryBasketsQuotaExceededException - Thrown if a new temporary basket cannot be created because the maximum number of temporary baskets per customer would be exceeded.
  • 400 - DuplicateShipmentIdException - Indicates that the same shipment id appeared twice in the body.
  • 400 - InvalidCustomerException - Thrown if the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
  • 400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
  • 400 - InvalidPriceAdjustmentLevelException - Indicates that a fixed price adjustment was added at order level which is disallowed.
  • 400 - InvalidPromotionIdException - When attempting to add a price adjustment, indicates that a promotion id was used twice.
  • 400 - MissingCouponCodeException - Thrown if the coupon number is not provided.
  • 400 - SystemPromotionIdException - When attempting to add a price adjustment, indicates that a system promotion id was used as a manual promotion id.
  • 400 - TooManyPromotionsException - Indicates that more than one hundred price adjustments would have been created.
  • 404 - ShipmentNotFoundException - Thrown if the shipment with the given shipment id is unknown.

Parameters

  • temporary (query, boolean) The boolean flag for creating the basket as temporary.

Request body

Media type: application/json, text/xml. Schema: basket.

Responses

  • 400 CustomerBasketsQuotaExceededException - Thrown if a new basket cannot be created because the maximum number of baskets per customer would be exceeded. or CustomerTemporaryBasketsQuotaExceededException - Thrown if a new temporary basket cannot be created because the maximum number of temporary baskets per customer would be exceeded. or DuplicateShipmentIdException - Indicates that the same shipment id appeared twice in the body. or InvalidCustomerException - Thrown if the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable. or InvalidPriceAdjustmentLevelException - Indicates that a fixed price adjustment was added at order level which is disallowed. or InvalidPromotionIdException - When attempting to add a price adjustment, indicates that a promotion id was used twice. or MissingCouponCodeException - Thrown if the coupon number is not provided. or SystemPromotionIdException - When attempting to add a price adjustment, indicates that a system promotion id was used as a manual promotion id. or TooManyPromotionsException - Indicates that more than one hundred price adjustments would have been created.

    Media type: application/json, text/xml. Schema: fault.

  • 404 ShipmentNotFoundException - Thrown if the shipment with the given shipment id is unknown.

    Media type: application/json, text/xml. Schema: fault.

  • default

    Media type: application/json, text/xml. Schema: basket.