Guides
My Account

    Create and validate promotional pricing in Dynamic sandbox

    Use this recipe to create a promotion for a test SKU in the Dynamic sandbox, place a test order after the promotion is in effect, and verify that the promotional price is applied correctly.

    Workflow

    This workflow shows you how to validate promotional pricing end-to-end in the Dynamic sandbox.

    Setup
    1. Authenticate
    2. Verify base price
    Create promotion
    1. Create promotion
    2. Verify promotion
    Validate
    1. Place test order
    2. Verify promotional price

    Before you begin

    To complete this recipe, you need Dynamic sandbox API credentials. Use your credentials to generate an OAuth access token before calling the APIs in this workflow.

    For more information about authentication and authorization, refer to the Authentication API.

    Prerequisites

    Before running this recipe, you must:

    1. Have a test SKU created in the Dynamic sandbox.
    2. Have a test fulfillment center (FC) created.
    3. Have inventory added to the test SKU at the test FC.

    Step 1: Authenticate

    Obtain an OAuth access token for subsequent API requests in this workflow.

    Endpoint
    POST /v3/token
    Requirements

    You must have valid sandbox clientId and clientSecret credentials. The authorization value uses the Base64-encoded clientId:clientSecret pair.

    Sample request
    curl --location 'https://sandbox.walmartapis.com/v3/token' \ --header 'Accept: application/json' \ --header 'Authorization: <base64(clientId:clientSecret)>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'WM_MARKET: us' \ --header 'WM_QOS.CORRELATION_ID: test-correlation-id' \ --header 'WM_SVC.NAME: MP' \ --data-urlencode 'grant_type=client_credentials'
    import requests url = "https://sandbox.walmartapis.com/v3/token" headers = { "Accept": "application/json", "Authorization": "<base64(clientId:clientSecret)>", "Content-Type": "application/x-www-form-urlencoded", "WM_MARKET": "us", "WM_QOS.CORRELATION_ID": "test-correlation-id", "WM_SVC.NAME": "MP",
} data = { "grant_type": "client_credentials",
} response = requests.post(url, headers=headers, data=data)
response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class GetSandboxToken { public static void main(String[] args) throws Exception { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://sandbox.walmartapis.com/v3/token")) .header("Accept", "application/json") .header("Authorization", "<base64(clientId:clientSecret)>") .header("Content-Type", "application/x-www-form-urlencoded") .header("WM_MARKET", "us") .header("WM_QOS.CORRELATION_ID", "test-correlation-id") .header("WM_SVC.NAME", "MP") .POST(HttpRequest.BodyPublishers.ofString( "grant_type=client_credentials" )) .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect

    Use the access token returned by the authentication request in the WM_SEC.ACCESS_TOKEN header for subsequent API calls in this workflow.

    Step 2: Verify the base price for the test SKU

    Confirm the current base price of the test SKU before creating a promotion.

    Endpoint
    GET /v1/simulations/items/{sku}
    Requirements
    • Use the access token obtained in Step 1.
    • The test SKU must already exist in the Dynamic Sandbox.
    Sample request
    curl --location 'https://sandbox.walmartapis.com/v1/simulations/items/{{sku}}' \ --header 'WM_SEC.ACCESS_TOKEN: {{token}}' \ --header 'WM_SVC.NAME: MP' \ --header 'WM_SANDBOX: v2' \ --header 'Accept: application/json'
    import requests sku = "{{sku}}" url = f"https://sandbox.walmartapis.com/v1/simulations/items/{sku}" headers = { "WM_SEC.ACCESS_TOKEN": "{{token}}", "WM_SVC.NAME": "MP", "WM_SANDBOX": "v2", "Accept": "application/json",
} response = requests.get(url, headers=headers)
response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class GetSandboxItem { public static void main(String[] args) throws Exception { String sku = "{{sku}}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create( "https://sandbox.walmartapis.com/v1/simulations/items/" + sku )) .header("WM_SEC.ACCESS_TOKEN", "{{token}}") .header("WM_SVC.NAME", "MP") .header("WM_SANDBOX", "v2") .header("Accept", "application/json") .GET() .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect
    • Verify the current base price for the test SKU.
    • Note the base price so you can set the promotional price below it in Step 3.

    Step 3: Create a promotion for the test SKU

    Create a promotion for the test SKU with a promotional price that is lower than the base price.

    Note: Promotion effectiveDate and expirationDate values must use ISO 8601 UTC format. The effectiveDate must be more than 30 minutes from the current time.

    Endpoint
    PUT /v3/price?promo=true
    Requirements
    • Use the access token obtained in Step 1.
    • The promotional currentPrice must be less than the base price confirmed in Step 2.
    • The effectiveDate must be more than 30 minutes from the current time.
    Sample request
    curl --location --request PUT 'https://sandbox.walmartapis.com/v3/price?promo=true' \ --header 'WM_QOS.CORRELATION_ID: test-correlation-id' \ --header 'WM_SEC.ACCESS_TOKEN: {{token}}' \ --header 'WM_SVC.NAME: MP' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'WM_SANDBOX: v2' \ --data '{ "offerId": "TestOffer", "sku": "{{sku}}", "replaceAll": "true", "pricing": [ { "currentPriceType": "REDUCED", "currentPrice": { "currency": "USD", "amount": 50 }, "comparisonPrice": { "currency": "USD", "amount": 100 }, "effectiveDate": "2026-10-01T00:00:00.000Z", "expirationDate": "2026-10-03T00:00:00.000Z", "promoId": "TestPromo", "processMode": "UPSERT", "comparisonPriceType": "BASE", "priceDisplayCodes": "CART" } ]
}'
    import requests url = "https://sandbox.walmartapis.com/v3/price" params = { "promo": "true",
} headers = { "WM_QOS.CORRELATION_ID": "test-correlation-id", "WM_SEC.ACCESS_TOKEN": "{{token}}", "WM_SVC.NAME": "MP", "Accept": "application/json", "Content-Type": "application/json", "WM_SANDBOX": "v2",
} payload = { "offerId": "TestOffer", "sku": "{{sku}}", "replaceAll": "true", "pricing": [ { "currentPriceType": "REDUCED", "currentPrice": { "currency": "USD", "amount": 50, }, "comparisonPrice": { "currency": "USD", "amount": 100, }, "effectiveDate": "2026-10-01T00:00:00.000Z", "expirationDate": "2026-10-03T00:00:00.000Z", "promoId": "TestPromo", "processMode": "UPSERT", "comparisonPriceType": "BASE", "priceDisplayCodes": "CART", } ],
} response = requests.put( url, headers=headers, params=params, json=payload,
) response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class CreateSandboxPromo { public static void main(String[] args) throws Exception { String body = """ { "offerId": "TestOffer", "sku": "{{sku}}", "replaceAll": "true", "pricing": [ { "currentPriceType": "REDUCED", "currentPrice": { "currency": "USD", "amount": 50 }, "comparisonPrice": { "currency": "USD", "amount": 100 }, "effectiveDate": "2026-10-01T00:00:00.000Z", "expirationDate": "2026-10-03T00:00:00.000Z", "promoId": "TestPromo", "processMode": "UPSERT", "comparisonPriceType": "BASE", "priceDisplayCodes": "CART" } ] } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create( "https://sandbox.walmartapis.com/v3/price?promo=true" )) .header("WM_QOS.CORRELATION_ID", "test-correlation-id") .header("WM_SEC.ACCESS_TOKEN", "{{token}}") .header("WM_SVC.NAME", "MP") .header("accept", "application/json") .header("content-type", "application/json") .header("WM_SANDBOX", "v2") .PUT(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect

    After submitting the promotion, continue to Step 4 to verify that it was successfully created before placing a test order.

    Step 4: Verify the promotion was created

    Verify that the promotion was successfully created for the test SKU.

    Endpoint
    GET /v3/promo/sku/{sku}
    Requirements
    • Use the access token obtained in Step 1.
    • Use the sku for the promotion created in Step 3.
    Sample request
    curl --location 'https://sandbox.walmartapis.com/v3/promo/sku/{{sku}}' \ --header 'WM_QOS.CORRELATION_ID: Test123' \ --header 'WM_SEC.ACCESS_TOKEN: {{token}}' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --header 'accept: application/json' \ --header 'WM_SANDBOX: v2'
    import requests sku = "{{sku}}" url = f"https://sandbox.walmartapis.com/v3/promo/sku/{sku}" headers = { "WM_QOS.CORRELATION_ID": "Test123", "WM_SEC.ACCESS_TOKEN": "{{token}}", "WM_SVC.NAME": "Walmart Service Name", "Accept": "application/json", "WM_SANDBOX": "v2",
} response = requests.get(url, headers=headers)
response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class GetSandboxPromo { public static void main(String[] args) throws Exception { String sku = "{{sku}}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create( "https://sandbox.walmartapis.com/v3/promo/sku/" + sku )) .header("WM_QOS.CORRELATION_ID", "Test123") .header("WM_SEC.ACCESS_TOKEN", "{{token}}") .header("WM_SVC.NAME", "Walmart Service Name") .header("accept", "application/json") .header("WM_SANDBOX", "v2") .GET() .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect

    Verify that the promotion was successfully created for the test SKU. Before continuing to Step 5, wait until the promotion is in effect.

    Step 5: Place a test order for the test SKU

    After the promotion is in effect, place a test order for the test SKU.

    Endpoint
    POST /v1/simulations/orders
    Requirements
    • Use the access token obtained in Step 1.
    • Wait until the promotion is in effect before placing the order.
    • The test SKU must have inventory at the test FC.
    Sample request
    curl --location 'https://sandbox.walmartapis.com/v1/simulations/orders' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'WM_SEC.ACCESS_TOKEN: {{token}}' \ --header 'WM_SVC.NAME: MP' \ --header 'WM_SANDBOX: v2' \ --data-raw '{ "customerEmailId": "[email protected]", "shippingInfo": { "phone": "0000000", "postalAddress": { "name": "Test User", "address1": "1 Customer Drive", "city": "Bentonville", "state": "AR", "postalCode": "72716", "country": "USA", "addressType": "RESIDENTIAL" } }, "orderLines": { "orderLine": [ { "item": { "sku": "{{sku}}" }, "orderLineQuantity": { "unitOfMeasurement": "EACH", "amount": "10" } } ] }
}'
    import requests url = "https://sandbox.walmartapis.com/v1/simulations/orders" headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_SEC.ACCESS_TOKEN": "{{token}}", "WM_SVC.NAME": "MP", "WM_SANDBOX": "v2",
} payload = { "customerEmailId": "[email protected]", "shippingInfo": { "phone": "0000000", "postalAddress": { "name": "Test User", "address1": "1 Customer Drive", "city": "Bentonville", "state": "AR", "postalCode": "72716", "country": "USA", "addressType": "RESIDENTIAL", }, }, "orderLines": { "orderLine": [ { "item": { "sku": "{{sku}}", }, "orderLineQuantity": { "unitOfMeasurement": "EACH", "amount": "10", }, } ] },
} response = requests.post( url, headers=headers, json=payload,
) response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class PlaceSandboxTestOrder { public static void main(String[] args) throws Exception { String body = """ { "customerEmailId": "[email protected]", "shippingInfo": { "phone": "0000000", "postalAddress": { "name": "Test User", "address1": "1 Customer Drive", "city": "Bentonville", "state": "AR", "postalCode": "72716", "country": "USA", "addressType": "RESIDENTIAL" } }, "orderLines": { "orderLine": [ { "item": { "sku": "{{sku}}" }, "orderLineQuantity": { "unitOfMeasurement": "EACH", "amount": "10" } } ] } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create( "https://sandbox.walmartapis.com/v1/simulations/orders" )) .header("Accept", "application/json") .header("Content-Type", "application/json") .header("WM_SEC.ACCESS_TOKEN", "{{token}}") .header("WM_SVC.NAME", "MP") .header("WM_SANDBOX", "v2") .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect

    Save the purchaseOrderId returned for the test order; it is required in Step 6.

    Step 6: Verify the promotional price was charged

    Retrieve the test order and verify that the promotional price was charged for the test SKU.

    Endpoint
    GET /v3/orders/{purchaseOrderId}
    Requirements
    • Use the access token obtained in Step 1.
    • Use the purchaseOrderId from the test order created in Step 5.
    Sample request
    curl --location 'https://sandbox.walmartapis.com/v3/orders/{{purchaseOrderId}}' \ --header 'Accept: application/json' \ --header 'WM_SANDBOX: v2' \ --header 'WM_SEC.ACCESS_TOKEN: {{token}}' \ --header 'WM_SVC.NAME: MP' \ --header 'WM_QOS.CORRELATION_ID: test-correlation-id'
    import requests purchase_order_id = "{{purchaseOrderId}}" url = ( "https://sandbox.walmartapis.com/v3/orders/" + purchase_order_id
) headers = { "Accept": "application/json", "WM_SANDBOX": "v2", "WM_SEC.ACCESS_TOKEN": "{{token}}", "WM_SVC.NAME": "MP", "WM_QOS.CORRELATION_ID": "test-correlation-id",
} response = requests.get(url, headers=headers)
response.raise_for_status() print(response.json())
    import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse; public class GetSandboxTestOrder { public static void main(String[] args) throws Exception { String purchaseOrderId = "{{purchaseOrderId}}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create( "https://sandbox.walmartapis.com/v3/orders/" + purchaseOrderId )) .header("Accept", "application/json") .header("WM_SANDBOX", "v2") .header("WM_SEC.ACCESS_TOKEN", "{{token}}") .header("WM_SVC.NAME", "MP") .header("WM_QOS.CORRELATION_ID", "test-correlation-id") .GET() .build(); HttpClient client = HttpClient.newHttpClient(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println(response.statusCode()); System.out.println(response.body()); }
}
    What to expect

    Confirm that the price charged for the test SKU matches the promotional currentPrice set in Step 3 rather than the base price confirmed in Step 2.

    Verify the results

    After completing this recipe, verify that:

    • You can generate a sandbox access token.
    • You can retrieve the base price for a test SKU.
    • You can create a promotion for a test SKU at a price below its base price.
    • You can retrieve the promotion after it is created.
    • You can place a test order after the promotion is in effect.
    • The test order reflects the promotional price rather than the base price.

    Next steps

    After confirming that the promotional price is applied correctly, you can repeat this workflow with different currentPriceType and comparisonPriceType combinations or test promotion expiration by placing an order after the expirationDate has passed.

    Related resources

    Updated 7 days ago

    Did this page help you?