Documentation
Feedback
Guides
API Reference

Guides
API usage
Making your first request
Learn how to make an API request

You can use the TEST METHOD button in VTEX API reference to test API requests as you read the documentaion. In this tutorial you will learn how to use this feature.

Before starting

Each request to VTEX APIs must be authenticated, either with application keys or user tokens. The Developers Portal TEST METHOD requires application keys, meaning a pair of appKey and appToken.

So before proceeding with this guide, make sure you have a valid pair of appKey and appToken with the necessary permissions to execute the requests you want. If you do not have this credential yet, learn more about how to create application keys.

Trying out a simple GET

The example below is based on the List orders endpoint, but these instructions apply for any endpoint you wish to try. Feel free to follow along.

To try out an API request follow these steps:

  1. Head to the API reference page of the endpoint you wish to test, such as the List orders endpoint.

    {"base64":"  ","img":{"width":1879,"height":823,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":107893,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Getting-Started/getting-started/making-your-first-request-1.png"}}

  2. Read the documentation and fill in necessary parameters of your request, such as headers, query parameters, and request body fields.

  3. Scroll to the TEST METHOD button. It may be on the top of the page at the right side of your screen, or on the bottom, depending on your window size.

  4. Fill in your app key in the X-VTEX-API-AppKey field.

  5. Fill in your app token in the X-VTEX-API-AppToken field.

  6. Hover your mouse cursor over the Base URL field to see the accountName and environment.

  7. Fill in the accountName field with your VTEX account name.

  8. Fill in the environment. If you do not know which environment to use, try vtexcommercestable.

    {"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7ljmRAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAMklEQVR4nAEnANj/AKeoqM/P0M/P0Nra2gDCwsLm5uZycnMzMzQADw8PEhERXV1dn5+gy2YToULBKD0AAAAASUVORK5CYII=","img":{"src":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Getting-Started/getting-started/making-your-first-request-2.png","width":1121,"height":739,"type":"png"}}

  9. Click the TEST METHOD button. This will send your request to the desired API endpoint.

  10. Check your response below the request.

{"base64":"  ","img":{"width":1096,"height":651,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":103861,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Getting-Started/getting-started/making-your-first-request-3.png"}}

If you get a 401 - Unauthorized as response, review the application key and token and try again. Make sure that the right permissions are defined in the roles and that you copied the exact key and token values into the headers of the request.

Learn more about VTEX authentication for developers.

If you received a 200 OK response, it means you got your a successful request to VTEX APIs.

Some API requests may return other status codes in case of success, such as 201 Created or 204 No Content.

Using an API testing platform

You can export API specification or example requests to be used with Postman or the API platform of your choice.

Request examples

As you fill in request parameters in VTEX API reference, as described above in steps 4 to 8, the request box is automattically updated. You can find this box below the Base URL field described above.

{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIAAAAmkwkpAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAP0lEQVR4nAE0AMv/ANvb27GxsqKipLS0twD5+Pr19fVISk8AAg0A1dXYu762vcG7foGBANDR09DQ0MfJx9/g3l+IIak+a5oIAAAAAElFTkSuQmCC","img":{"src":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Getting-Started/getting-started/making-your-first-request-4.png","width":359,"height":315,"type":"png"}}

This means you can copy this content to be imported into other software.

Downloading API specifications

Our API reference documentation is built using the Open API 3.0 (OAS 3.0) standard. The OAS 3.0 schemas are available for download in our GitHub repository.

{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAIAAADwyuo0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAJUlEQVR4nAEaAOX/AMTHyauqrZijlmZ+ZgDw8fLLztEYNEwADSzLig2AyXqjRgAAAABJRU5ErkJggg==","img":{"src":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/getting-started-making-your-first-request-2.png","width":433,"height":214,"type":"png"}}

Using postman

You can import our OAS API specification to Postman by downloading the JSON schemas you are interested in and following these instructions.

If you have copied a cURL request example, you can also import it into Postman as raw text.

Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page