To authenticate an API call successfully, pass your Consumer ID and digital signature in the API header for every API call you make.To authenticate an API call successfully, pass your Consumer ID and digital signature in the API header for every API call you make.To authenticate an API call successfully, pass your Consumer ID and digital signature in the API header for every API call you make.
First, register as a Marketplace Seller and get your Consumer ID and Private Key during the onboarding process or by logging in to Seller Center. Then, use these keys, along with other headers to generate the digital signature.
Integration Steps
- Pick a simple call using the GET method, such as Get All Feed Statuses.
- Generate a digital signature, either:
- Generate the Digital Signature Using an Executable JAR file (Recommended)
- Generate the Digital Signature Using Self-written Code
We strongly recommend using the executable JAR file because it eliminates the vast majority of issues for authenticating calls.
- Pass the header keys listed in the table below to authenticate your API call.
- Make sure the call does not throw a 400 or 401 error. For more information, refer to Error Codes.
- If a 400 HTTP status code is thrown, ensure that all of the mandatory headers are passed. Also validate all mandatory query or path parameters as well as the proper Accept HTTP header.
- If a 401 HTTP status code is thrown, verify your generated digital signature to make sure that the required parameters were passed to your authentication code.
If you are having trouble connecting to Walmart Developer Portal, refer to Troubleshooting.
Note: WM_CONSUMER.CHANNEL.TYPE is a mandatory header for V3 APIs. You can get the header value when you log in to Seller Center. For more details, refer to the article: API Settings
| Name | Description | Required | Example |
|---|---|---|---|
| WM_SVC.NAME | Walmart Service Name | Yes | Walmart Gateway API |
| WM_QOS.CORRELATION_ID | A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID | Yes | 1234hfvgtr |
| WM_SEC.TIMESTAMP | The Epoch timestamp | Yes | 1443748249449 |
| WM_SEC.AUTH_SIGNATURE | The vendor’s digital signature, generated by running the JAR file or custom generation code | Yes | 9fg3TPeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs 8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYH L27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDD hbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg= |
| WM_CONSUMER.CHANNEL.TYPE | A unique ID to track the consumer request by channel | Yes for V3, optional for V2 | 0f3e4dd4-0514-4346-b39d-… use the Consumer Channel Type received during onboarding |
| WM_CONSUMER.ID | A unique ID required to access the API | Yes | Get the Consumer ID from Developer Center after logging in |
| WM_TENANT_ID | The marketplace name. Example: Walmart_CA | Yes | WALMART.CA |
| WM_LOCALE_ID | The geographic location when using API endpoints outside the US | Yes | ‘en_CA’ (Default) or ‘fr_CA’ |
| Accept | The returned data format in the response | No | application/xml |
Generate the Digital Signature Using an Executable JAR file (Recommended)
To generate your digital signature using the executable JAR file, follow these steps:
- Download Java 6.0 or greater. If it is not installed on your computer, go to: https://java.com/en/download
- Download the Digital Signature executable JAR file.
- Use the following command to run the executable JAR file:
java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil {requestUrl} {consumerId} {privateKey} {requestMethod} {filePath}The executable JAR file uses five parameters, see the table below:
| Name | Description | Required |
|---|---|---|
| requestUrl | The full URL to call, including path and query parameters | Yes |
| consumerId | The Consumer ID retrieved from Developer Center after login | Yes |
| privateKey | The vendor’s Base-64-encoded, PKCS#8 stored Private Key | Yes |
| requestMethod | Use method GET (all capital letters) to call this API | Yes |
| filePath | The absolute (full) path of the file desired for the digital signature and timestamp. The digital signature and timestamp can also be viewed in the console. | Yes |
Note: Your program must run this executable JAR file in the directory where the executable JAR file is located.
Running the executable JAR file returns the following two headers as the console output.
- WM_SEC.AUTH_SIGNATURE
- WM_SEC.TIMESTAMP
Note: Generate the signature and a timestamp for every API call, even if it is for the same API.
Generate the Digital Signature Using Self-written Code
To get the digital signature using your own code, follow these steps:
- Get the Consumer ID and your Base 64-encoded Private Key you generated in Seller Center.
- Get the full URL you wish to call, including any path and query parameters.
- Use the GET method to construct an input for the digital signature.
- Use the structure listed below: The Consumer ID issued to you_ + “\n” + the URL of the API call you are making + “\n” + the request method of the API call you are making in all capitals + “\n” + the Unix Epoch timestamp now (in milliseconds since Jan 01 1970 UTC) + “\n”
- Generate the byte array of the structured data listed in step 3 using the following steps:
- Decode the byte array with Base-64.
- Encode the resulting value using PKCS#8 to represent your Private Key. Libraries in various languages offer the ability to identify that the Private Key is in PKCS#8 format and not in other conflicting formats such as PKCS#1.
- Use this byte representation of your private key to sign the data using SHA-256 with RSA.
- Encode the generated digital signature using Base-64.
- Use the generated digital signature and the timestamp to make your API call.
Troubleshooting
New users may have difficulties integrating with the platform for the first time. Typically, errors occur when incorrect headers are generated (such as the timestamp or authentication signature). To avoid errors, use the headers listed in the header samples displayed in the corresponding section.
Testing the API Calls:
To accelerate development, you can use an online tool such as the Google Chrome Advanced REST Client App (ARCA), Postman, etc.
To test your API calls using the ARCA, follow the steps below:
- Enter the URL: https://marketplace.walmartapis.com/v3/feeds
- Select GET from the drop-down menu.
- Configure the headers as listed in step 3 of the ‘Integration Steps’ section.
- Click Send.
If basic API calls are successful from the ARCA, but not from your own code, the problem lies in your own code. If the calls fail from the ARCA, there is a problem with your headers.
Troubleshooting Hints
- If the call from the ARCA succeeds, your headers are correct. But if your code fails, examine the headers.
- If the call from the ARCA fails and you are not using the executable JAR file, generate the headers using the executable JAR file and try again. If the call now succeeds, either start using the executable JAR file in your processes, or adjust your own code to correctly generate the headers.
- If the call from the ARCA fails and you are using the executable JAR file, generate a new set of credentials from Seller Center and retry with the new credentials (this ensures that the credentials are not obsolete, or you have not reset your Private Key recently).
- If you are sure that you have configured the ARCA correctly and you are using the most current credentials, but are still getting errors, contact Walmart Marketplace Support.