Point of Sale Developer Guide for Non Hyperforce Users

Invoking Point of Sale APIs is a two-step process. This topic describes the steps and includes sample responses.

For a comprehensive list of APIs and SPIs, see Point of Sale API Specifications.

note: In 2024, Salesforce acquired PredictSpring, a provider of modern retail point-of-sale (POS) software built natively in the cloud. PredictSpring was renamed Retail Cloud and is now called Point of Sale. You may still see references to PredictSpring or Retail Cloud in the Point of Sale app and in our documentation (for example, in API header names).

API Keys

Find the keys needed to use Point of Sale APIs in CMS by going to Advanced > Merchant Configuration > Developer Credentials.

Base URL

• Staging API Base URL: https://api.predictspring.com/staging/service
• Production API Base URL: https://api.predictspring.com/prod/service
• Staging OAuth2 URL: https://staging-oauth2.predictspring.com/oauth2/token
• Production OAuth2 URL: https://prod-oauth2.predictspring.com/oauth2/token

API Inbound Rate Limits

• Production: 10 requests per second and 100,000 requests per month.
• Staging: 10,000 requests per month.

For additional API volume, contact Salesforce Customer Support.

Configuration and Setup

To use Point of Sale APIs, complete a two-step authentication process. First, obtain an OAuth token. Then, use that token to make API calls.

Step 1: Get OAuth token

curl -X POST \
  '<OAuth2 URL>?grant_type=client_credentials' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Authorization: Basic <BASE64 ENCODED ClientID:ClientSecret>' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Length: ' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache'

Sample Response:

{
  "access_token": "<access token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Extract the access token value. This token is required for Step 2 to invoke the Point of Sale API.
The token is valid for the expiry period as specified in expired_in in seconds.

Pass the access token as PredictSpring-Token when invoking the Point of Sale API.

Step 2: Invoke API

note: Make sure that Content-Type is set to application/json in all the requests.

Invoke Point of Sale API with the below headers:

1. PredictSpring-Secret (this is an encrypted string you get from Point of Sale)
2. PredictSpring-Token
3. X-api-key
4. Content-Type: application/json

note: x-api-key is the Merchant API Key in the UI.

Here's a sample request to create promotions in a staging environment.

curl -X POST \
  https://api.predictspring.com/staging/service/merchant/v1/promotions \
  -H 'Content-Type: application/json' \
  -H 'PredictSpring-Secret: <PredictSpring-Secret>' \
  -H 'PredictSpring-Token: <Access-Token>' \
  -H 'x-api-key: <x-api-key>' \
  -d '{
    "hasSingleUsePromoCodes": false,
    "active": true,
    "promotionType": "ORDER_AMOUNT_OFF",
    "name": "Special Promo",
    "amountOff": 0.99,
    "title": "Special Promo for you!",
    "description": "Special promo test",
    "imageUrl": "<image url>",
    "startTimeStamp": 1567321200000,
    "endTimeStamp": 1567494000000,
    "merchantPromotionId": "ext-special-promo-1",
    "auto": true,
    "redemptionLimit": 1,
    "rules": [
        {
            "promotionRuleType": "PRODUCT",
            "operator": "INCLUSIVE",
            "value": [
                "1366160159739842"
            ]
        },
        {
            "promotionRuleType": "CATEGORY",
            "operator": "INCLUSIVE",
            "value": [
                "Clothing"
            ]
        },
        {
            "promotionRuleType": "PRODUCT",
            "operator": "EXCLUSIVE",
            "value": [
                "1366160159794742"
            ]
        }
    ],
    "channel": [
        "APP",
        "STORE",
        "OUTLET"
    ],
    "combinationTypes": [
        "ORDER_PERCENT_OFF",
        "ORDER_AMOUNT_OFF",
        "FREE_SHIPPING",
        "BOGO",
        "FREE_SAMPLES",
        "PRODUCT_FIXED_AMOUNT",
        "X_FOR_Y"
    ]
}'