Place an order with Salesforce Commerce Cloud API

Step-by-step guide on how to place an order with guest shopper while using Salesforce Shopper Login and API Access Service (SLAS)

6 min readApr 14, 2022

In this article, I will share a nine-step bash-based solution to place an order with the guest shopper by leveraging Salesforce Shopper Login and API Access Service (SLAS). The scripts and idea to place an order from the bash script belong to John Boxall, and I wish to share my appreciation that John agreed that I would write this guide and use his scripts for our Commerce Cloud community.

Step 0. Set the variables

#!/bin/sh
# SCAPI Checkout Flow with Guest from SLAS client_credentials
set -eu

SHORTCODE='qw1ert23'
ORG='f_ecom_abcd_001'
SITE="RefArchGlobal"
SLAS_CLIENT_ID='q12we345-6789-01rt-234y-u56iopa789s0'
SLAS_CLIENT_SECRET='ALOHOMORA'

BASE="https://$SHORTCODE.api.commercecloud.salesforce.com"

SHORTCODE — The shortcode is an eight-character value assigned to a realm for routing purposes. The shortcode applies to your entire realm environment across all instances.
ORG — The organization ID is based on the realm and instance that you want to access with the Commerce API. The organization ID is different for each instance: production, staging, development, and sandbox. To form the organization ID, concatenate the realm ID and instance ID as follows: f_ecom_{{realm_id}}_{{instance_id}}. For example, for realm axgy and sandbox s05, the organization ID is f_ecom_axgy_s05. If you have the Business Manager Administrator role, you can see both the shortcode and organization ID in Business Manager. Go to Administration > Site Development > Salesforce Commerce API Settings. If you’ve never used the Commerce API in your realm, click Request Short Code to assign a shortcode for your realm.
SITE — The API site ID is the name of the site for which you want to access data, for example RefArch or SiteGenesis. To see a list of sites in Business Manager, go to Administration > Sites > Manage Sites. See Create a Site in Business Manager for information about site names in the user documentation.
SLAS_CLIENT_ID — SLAS Client ID, which is not an Account Manager Client ID. See Setting Up API Access in the user documentation for information about SLAS Client ID
SLAS_CLIENT_SECRET — SLAS Client Secrret, which is not an Account Manager Client Secret. See Setting Up API Access in the user documentation for information about SLAS Client Secret.
BASE — API hostname for your API calls is created by using the shortcode, which is concatenated with api.commercecloud.salesforce.com. For example: u8ak193h.api.commercecloud.salesforce.com.

Step 1. Get Guest Token

# 1. Get Guest Token: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getAccessToken
TOKEN=$(curl "$BASE/shopper/auth/v1/organizations/$ORG/oauth2/token" \
    -su "$SLAS_CLIENT_ID:$SLAS_CLIENT_SECRET" \
    -d 'grant_type=client_credentials' | jq -r .'access_token')

Step 2. Create a Basket

# 2. Create a Basket: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:createBasket
BASKET=$(curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets?siteId=$SITE" \
    -sX 'POST' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "productItems": [{ "quantity": 1, "productId": "682875090845M"}]}' | jq -r '.basketId')

jq -r will extract the basket ID into a BASKET variable that is going to be used across all steps.

682875090845M This is an ID of the product with the quantity 1 we are creating a basket with.

Step 3. Set the Customer

# 3. Set the Customer:
https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:updateCustomerForBasket
curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/customer?siteId=$SITE" \
    -o /dev/null \
    -sX 'PUT' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "email": "john.boxall@sample.com" }'

john.boxall@sample.com — This is the email address of our guest shopper who is placing an order.

Step 4. Set Shipping Address

# 4. Set Shipping Address. https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:createShipmentForBasket
curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/shipments/me?siteId=$SITE" \
    -o /dev/null \
    -sX 'PATCH' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Boxall",
    "address1": "415 Mission St.",
    "city": "San Francisco",
    "postalCode": "94105",
    "stateCode": "CA",
    "countryCode": "US"
  }
}'

With Salesforce Commerce APIs you can create and name different shipments. By default initially provided shipment address will be associated with baskets me shipment.

shippingAddress.firstName — shopper First Name.
shippingAddress.lastName — shopper Last Name.
shippingAddress.address1 — shopper Address to where the order will be shipped.
shippingAddress.city — shopper City to where the order will be shipped.
shippingAddress.postalCode — shopper Postal Code to where the order will be shipped.
shippingAddress.stateCode — shopper State Code to where the order will be shipped.
shippingAddress.countryCode — shopper Country Code to where the order will be shipped.

Step 5. Get the first applicable Shipping Method

# 5. Get the first applicable Shipping Method: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:getShippingMethodsForShipment
SHIPPING_METHOD=$(curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/shipments/me/shipping-methods?siteId=$SITE" \
    -sH "Authorization: Bearer $TOKEN" | jq -r '.applicableShippingMethods[0].id')

jq -r will extract the first applicable shipping method into a SHIPPING_METHOD variable that is going to be used in Step 6.

Step 6. Set the Shipping Method

# 6. Set the Shipping Method: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:updateShippingMethodForShipment
curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/shipments/me/shipping-method?siteId=$SITE" \
    -o /dev/null \
    -sX 'PUT' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"id": "'$SHIPPING_METHOD'"}'

SHIPPING_METHOD is a value for the shipping method we received and stored in Step 5.

Round Up For Ukraine is an idea movement that enables businesses and people to use their power for peace. If there is any financial transaction in business day-to-day operations, such a business could round up transaction and use a change for charity organizations that supports Ukraine. Financial institutions, POS solutions, Grocery stores, eCommerce, Marketplaces, and many more businesses can apply Round Up For Ukraine starting today. For more information check https://roundupforukraine.org.

Step 7. Set the Payment Method

# 7. Set the Payment Instruments: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:addPaymentInstrumentToBasket

curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/payment-instruments?siteId=$SITE" \
    -o /dev/null \
    -sX 'POST' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "amount": 1,
  "paymentCard": {
    "issueNumber": "4111111111111111",
    "expirationYear": 2022,
    "expirationMonth": 12,
    "holder": "John Boxall",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}'

paymentCard.issueNumber — Credit Card (CC) number
paymentCard.expirationYear — CC Expiration Year
paymentCard.expirationMonth — CC Expiration Month
paymentCard.holder — CC Holder Name
paymentCard.cardType — CC Type
paymentMethodId — Commerce Cloud payment method ID

Step 7 is missing a security code attribute. In the future, this article needs an update on how to pass the security code to this API.

Step 8. Set Billing Address

https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-baskets:updateBillingAddressForBasket
curl "$BASE/checkout/shopper-baskets/v1/organizations/$ORG/baskets/$BASKET/billing-address?siteId=$SITE&useAsShipping=false" \
    -o /dev/null \
    -sX 'PUT' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "firstName": "John",
  "lastName": "Boxall",
  "address1": "415 Mission St",
  "city": "San Francisco",
  "postalCode": "94105",
  "stateCode": "CA",
  "countryCode": "US"
}'

firstName — shopper First Name.
lastName — shopper Last Name.
address1 — Address of the shopper’s billing addresses.
city — City of the shopper’s billing addresses.
postalCode — Postal Code of the shopper’s billing addresses.
stateCode — State Code of the shopper’s billing addresses.
countryCode — Country Code of the shopper’s billing addresses.

# 9. Submit the Order 🍾

https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-orders:createOrder
curl "$BASE/checkout/shopper-orders/v1/organizations/$ORG/orders?siteId=$SITE" \
    -sX 'POST' \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "basketId": "'$BASKET'"}'

This final step will submit the order!

If you wish to run scripts in automated mode copy/paste the full bash script from the following gist, replace credentials and run it into your console:

Helpful resources

My name is Oleg Sapishchuk, and I’m an experienced Architect providing digital transformation with unified commerce solutions for some of the world’s best-known and most influential brands. Salesforce B2C Commerce is the topic that I write about most frequently. If you are interested in new or previously written material, I invite you to follow my Medium profile.