Commerce API Workshop files: Collection and Environment for Postman are included.

Commerce API Workshop.postman_collection.json

{
	"info": {
		"_postman_id": "2798c320-a665-49db-94ed-ef104923fc71",
		"name": "Commerce API Workshop",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "1a. Guest customer token",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "148dc8c4-2b31-4524-b847-15cf64aeb8b7",
						"exec": [
							"pm.globals.set(\"custOauthToken\", pm.response.headers.get(\"Authorization\"));"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"type\" : \"guest\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{{organizationId}}/customers/actions/login?siteId={{siteId}}&clientId={{clientId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"customer",
						"shopper-customers",
						"v1",
						"organizations",
						"{{organizationId}}",
						"customers",
						"actions",
						"login"
					],
					"query": [
						{
							"key": "siteId",
							"value": "{{siteId}}"
						},
						{
							"key": "clientId",
							"value": "{{clientId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "1b. Product Details",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "Authorization",
						"value": "{{custOauthToken}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{{organizationId}}/products?ids={{productId}}&siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"product",
						"shopper-products",
						"v1",
						"organizations",
						"{{organizationId}}",
						"products"
					],
					"query": [
						{
							"key": "ids",
							"value": "{{productId}}"
						},
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "1c. Product Search",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "Authorization",
						"type": "text",
						"value": "{{custOauthToken}}"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/{{organizationId}}/product-search?q=ties&siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"search",
						"shopper-search",
						"v1",
						"organizations",
						"{{organizationId}}",
						"product-search"
					],
					"query": [
						{
							"key": "q",
							"value": "ties"
						},
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "1d. Promotion Details",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "Authorization",
						"type": "text",
						"value": "{{custOauthToken}}"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/pricing/shopper-promotions/v1/organizations/{{organizationId}}/promotions?ids={{promoId}}&siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"pricing",
						"shopper-promotions",
						"v1",
						"organizations",
						"{{organizationId}}",
						"promotions"
					],
					"query": [
						{
							"key": "ids",
							"value": "{{promoId}}"
						},
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "2a. Register a new customer (run 1a first, see 3c in case customer exists)",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "148dc8c4-2b31-4524-b847-15cf64aeb8b7",
						"exec": [
							"pm.globals.set(\"custOauthToken\", pm.response.headers.get(\"Authorization\"));",
							"pm.environment.set(\"customerNo\", pm.response.json().customerNo);"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"type": "text",
						"value": "application/json"
					},
					{
						"key": "Authorization",
						"value": "{{custOauthToken}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"customer\": {\n    \"email\": \"headlesshorseman@example.edu\",\n    \"firstName\": \"Headless\",\n    \"lastName\": \"Horseman\",\n    \"login\": \"headlesshorseman@example.edu\"\n  },\n  \"password\": \"!Sleepy2020\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{{organizationId}}/customers?siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"customer",
						"shopper-customers",
						"v1",
						"organizations",
						"{{organizationId}}",
						"customers"
					],
					"query": [
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "2b. Registered customer token",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "31b508ea-c381-4533-a188-46f0e90c925f",
						"exec": [
							"pm.globals.set(\"custOauthToken\", pm.response.headers.get(\"Authorization\"));"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"auth": {
					"type": "basic",
					"basic": [
						{
							"key": "username",
							"value": "headlesshorseman@example.edu",
							"type": "string"
						},
						{
							"key": "password",
							"value": "!Sleepy2020",
							"type": "string"
						},
						{
							"key": "saveHelperData",
							"value": true,
							"type": "boolean"
						},
						{
							"key": "showPassword",
							"value": true,
							"type": "boolean"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"type": "text",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"type\" : \"credentials\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{{organizationId}}/customers/actions/login?siteId={{siteId}}&clientId={{clientId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"customer",
						"shopper-customers",
						"v1",
						"organizations",
						"{{organizationId}}",
						"customers",
						"actions",
						"login"
					],
					"query": [
						{
							"key": "siteId",
							"value": "{{siteId}}"
						},
						{
							"key": "clientId",
							"value": "{{clientId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "2c. Create basket for registered customer",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "e7b071d0-6170-4963-a40b-396d5c85dd88",
						"exec": [
							"pm.test(\"Set Basket Id\", function () {\r",
							"   var jsonData = pm.response.json();\r",
							"   pm.environment.set(\"basketId\", jsonData.basketId);\r",
							"   console.log(\"basketId: \"+jsonData.basketId);\r",
							"   pm.response.to.have.status(200);\r",
							"});\r",
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Authorization",
						"value": "{{custOauthToken}}",
						"type": "text"
					},
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"productItems\": [\n    {\n      \"productId\": \"{{productId}}\",\n      \"quantity\": 1,\n      \"inventoryId\": \"inventory_m\"\n    }\n  ]\n}"
				},
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/{{organizationId}}/baskets?siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"checkout",
						"shopper-baskets",
						"v1",
						"organizations",
						"{{organizationId}}",
						"baskets"
					],
					"query": [
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "2d. Add item to basket for registered customer",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "a56b7d32-03ce-49a1-924e-2d27d8f4f61b",
						"exec": [
							"pm.test(\"Set Product Item Id\", function () {\r",
							"   var jsonData = pm.response.json();\r",
							"   pm.globals.set(\"newProductItem\", jsonData.productItems[2].itemId);\r",
							"   console.log(\"newProductItem: \"+jsonData.productItems[2].itemId);\r",
							"   pm.response.to.have.status(200);\r",
							"});\r",
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Authorization",
						"type": "text",
						"value": "{{custOauthToken}}"
					},
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"type": "text",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "[{\n    \"productId\": \"{{productId}}\",\n    \"quantity\": 1\n}]"
				},
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/{{organizationId}}/baskets/{{basketId}}/items?siteId={{siteId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"checkout",
						"shopper-baskets",
						"v1",
						"organizations",
						"{{organizationId}}",
						"baskets",
						"{{basketId}}",
						"items"
					],
					"query": [
						{
							"key": "siteId",
							"value": "{{siteId}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "3a. Admin API: Oauth2 access token (see Body for specific scopes)",
			"event": [
				{
					"listen": "test",
					"script": {
						"id": "6b6b423b-8a97-4fec-952e-75116a942aac",
						"exec": [
							"var tokenData = JSON.parse(responseBody);",
							"",
							"if(tokenData.access_token!==null && tokenData.token_type!==null ){",
							"    pm.globals.set(\"oAuthToken\", tokenData.token_type + \" \" + tokenData.access_token);",
							"}"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"auth": {
					"type": "basic",
					"basic": [
						{
							"key": "password",
							"value": "{{clientIdPwd}}",
							"type": "string"
						},
						{
							"key": "username",
							"value": "{{clientId}}",
							"type": "string"
						},
						{
							"key": "saveHelperData",
							"value": true,
							"type": "boolean"
						},
						{
							"key": "showPassword",
							"value": true,
							"type": "boolean"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"value": "application/x-www-form-urlencoded",
						"type": "text"
					}
				],
				"body": {
					"mode": "urlencoded",
					"urlencoded": [
						{
							"key": "grant_type",
							"value": "client_credentials",
							"type": "text"
						},
						{
							"key": "scope",
							"value": "SALESFORCE_COMMERCE_API:{{tenant}} sfcc.catalogs sfcc.customerlists.rw",
							"type": "text"
						}
					]
				},
				"url": {
					"raw": "https://account.demandware.com/dwsso/oauth2/access_token",
					"protocol": "https",
					"host": [
						"account",
						"demandware",
						"com"
					],
					"path": [
						"dwsso",
						"oauth2",
						"access_token"
					]
				}
			},
			"response": []
		},
		{
			"name": "3b. Admin API: Get customer (run 2a first)",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "Authorization",
						"value": "{{oAuthToken}}",
						"type": "text"
					},
					{
						"key": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/{{organizationId}}/customer-lists/{{listId}}/customers/{{customerNo}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"customer",
						"customers",
						"v1",
						"organizations",
						"{{organizationId}}",
						"customer-lists",
						"{{listId}}",
						"customers",
						"{{customerNo}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "3c. Admin API: Delete customer (run 3a and this if 2a fails)",
			"request": {
				"method": "DELETE",
				"header": [
					{
						"key": "Authorization",
						"type": "text",
						"value": "{{oAuthToken}}"
					},
					{
						"key": "Content-Type",
						"type": "text",
						"value": "application/json"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/{{organizationId}}/customer-lists/{{listId}}/customers/{{customerNo}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"customer",
						"customers",
						"v1",
						"organizations",
						"{{organizationId}}",
						"customer-lists",
						"{{listId}}",
						"customers",
						"{{customerNo}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "3d. Admin API: Get catalog (requires specific scope on 3a)",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "Authorization",
						"value": "{{oAuthToken}}",
						"type": "text"
					},
					{
						"key": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://{{shortCode}}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/{{organizationId}}/catalogs/{{catalogId}}",
					"protocol": "https",
					"host": [
						"{{shortCode}}",
						"api",
						"commercecloud",
						"salesforce",
						"com"
					],
					"path": [
						"product",
						"catalogs",
						"v1",
						"organizations",
						"{{organizationId}}",
						"catalogs",
						"{{catalogId}}"
					]
				}
			},
			"response": []
		}
	],
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"id": "ff2059b1-7d60-481a-9712-cc10e4646f19",
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"id": "ec0dc77c-1c5d-4896-b9ad-c6dad64e6c64",
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"protocolProfileBehavior": {}
}

Commerce API Workshop.postman_environment.json

{
	"id": "ee600b26-e175-4fc0-9653-0481082d473c",
	"name": "Commerce API Workshop",
	"values": [
		{
			"key": "clientId",
			"value": "get a client ID from Acccount Manager, API Client",
			"enabled": true
		},
		{
			"key": "clientIdPwd",
			"value": "this is the password for the clientId above",
			"enabled": true
		},
		{
			"key": "organizationId",
			"value": "f_ecom_<realm>_<instance>, for example f_ecom_zzpa_001",
			"enabled": true
		},
		{
			"key": "tenant",
			"value": "<realm>_<instance>, for example zzpa_001",
			"enabled": true
		},
		{
			"key": "siteId",
			"value": "RefArch",
			"enabled": true
		},
		{
			"key": "shortCode",
			"value": "get shorcode from the Salesforce Commerce API settings in BM",
			"enabled": true
		},
		{
			"key": "productId",
			"value": "793775362380M",
			"enabled": true
		},
		{
			"key": "productIds",
			"value": "P0048M,682875540326M",
			"enabled": true
		},
		{
			"key": "promoId",
			"value": "$5_off_ties_promotion",
			"enabled": true
		},
		{
			"key": "promoIds",
			"value": "$5_off_ties_promotion,15off-gps",
			"enabled": true
		},
		{
			"key": "basketId",
			"value": "",
			"enabled": true
		},
		{
			"key": "catalogId",
			"value": "apparel-m-catalog",
			"enabled": true
		},
		{
			"key": "listId",
			"value": "RefArch",
			"enabled": true
		},
		{
			"key": "customerNo",
			"value": "this gets generated by 2a. Register a new customer",
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2020-08-14T19:54:27.386Z",
	"_postman_exported_using": "Postman/7.30.1"
}

Hello all,
Environment variable values are mostly placeholders, so you must use your own clientID and sandbox to fill them.
Some values are hardcoded to represent a customer login: use as is, or change to your own email/pwd.
Any other values present assume SFRA RefArch site: products, promotions, catalog, customers lists, etc.

Update on July 24:

• Added new scopes for 3a. Admin API: Oauth2 get access token. This is required to narrow the scope of a token to certain endpoints. Restrictive but provides better security:
  "key": "scope",
  "value": "SALESFORCE_COMMERCE_API:zzpa_002 sfcc.catalogs sfcc.customerlists.rw",
  "type": "text"

• Don't forget to add the same scopes above (and more, if you need them) to your API Client for Commerce APIs in Account Manager:

  • sfcc.shopper-products
  • sfcc.shopper-product-search
  • sfcc.shopper-promotions
  • sfcc.shopper-customers.register
  • sfcc.shopper-customers.login
  • sfcc.shopper-baskets-orders.rw
  • sfcc.shopper-myaccount.baskets.rw
  • sfcc.catalogs
  • sfcc.customerlists.rw

Good luck!

The sleepyhollow-dot-com domain is owned by some Mr. Komonchak in TX. I am not sure if he appreciates the attention that his domain is getting from test customer registrations.

I propose to replace all sleepyhollow-dot-com" with example-dot-edu to be on the safe side :-)

Replace all -dot- above with a single dot "." before reading.

[edit: example-dot-com is not allowed, it fails customer account creation. example-dot-edu avoids that filter while still being an IANA reserved example domain]

In the postman environment, the variable "catalogId" has a trailing space character: "apparel-m-catalog " -- this causes the postman call in 3d. to respond with a 404 not found.

@alagopus, Danke Schoen for your comments. I've made the changes, hopefully the Sleepy Hollow historical reference does not die on the technical details!
Happy learning.

When I try to call 1a. Guest customer token I receive HTTP 308 Server Error with the following body:

{
"title": "This API is deprecated",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
"detail": "This API is deprecated. Please use the /login endpoint from the new Oauth2.0 based Shopper Login and API Access Service (Refer: https://developer.commercecloud.com/s/api-details/a003k00000VWfNDAA1/commerce-cloud-developer-centershopperloginandapiaccessservice)"
}

I tried to follow the documentation and created a request to https://{{shortCode}}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{{organizationId}}/oauth2/login but I get HTTP 401 with the response
{
"status_code": "401 UNAUTHORIZED",
"message": "Client Authentication failed"
}

I now my client ID is correct (3a runs fine) and it has all recommended allowed scopes in Account Manager.

Do you have an updated version of the postman collection or any idea of what may be wrong with my request?