openapi-schemas

This documentation comprises VTEX's public APIs as OpenAPI 3.0 JSON schemas. Files are automatically synced with VTEX's Developer Portal API Reference page and can be imported to Postman following these instructions.

Contributing with the documentation

Please check our Contributing Guide for more information about how to contribute with this repository.

Code of Conduct

Please read our Code of Conduct before contributing.

VTEX APIs

• Antifraud Provider API
• Catalog API Seller Portal
• Catalog API
• Checkout API
• Customer Credit API
• Data Subject Rights API
• GiftCard Hub API
• GiftCard API
• GiftCard Provider Protocol
• Headless CMS API
• Intelligent Search API
• Intelligent Search Events API - Headless
• Legacy CMS Portal API
• License Manager API
• Logistics API
• Marketplace APIs - Sent Offers
• Marketplace APIs - Suggestions
• Marketplace Protocol - External Marketplace Mapper
• Marketplace Protocol - External Marketplace Orders
• Marketplace Protocol - External Seller Fulfillment
• Marketplace Protocol - External Seller Marketplace
• Master Data API - v1
• Master Data API - v2
• Message Center API
• Orders API
• Orders API (PII compliant)
• Payment Provider Protocol
• Payments Gateway API
• Policies System API
• Price Simulations API
• Pricing API
• Pricing Hub
• Profile System API
• Promotions & Taxes API - v2
• Promotions & Taxes API
• Recurrence (v1 - deprecated)
• Reviews and Ratings API
• SKU Bindings API
• Search API
• Session Manager API
• Subscriptions (v2 - deprecated)
• Subscriptions (v3)
• VTEX Tracking API
• VTEX Do API
• VTEX ID API
• VTEX Shipping Network API

Requisites

Before contributing to this repository, read the following requisites.

• The files should follow the JSON OpenAPI 3.0 Specification.
• Check our internal OpenAPI Specification guidelines to make sure you meet the required file structure.
• Schema files should have a self-explanatory name that specifies the described API.
• Check templates/VTEX - Template openAPI.jsonc to see an example of an API schema file. It shows how to represent endpoints and parameters and includes VTEX's default servers and authorization information.

Servers

OpenAPI describes the full endpoint for accessing the API as {server URL} + {endpoint path} + {path parameters}.

Example: an endpoint with /api/getResults as the path, https://example.com as the URL in the server object and no parameters will send requests to the https://example.com/api/getResults URL.

Example - servers object:

"servers": [
    {
        "url": "https://{accountName}.{environment}.com.br",
        "description": "VTEX server URL.",
        "variables": {
            "accountName": {
                "description": "Name of the VTEX account. Used as part of the URL.",
                "default": "apiexamples"
            },
            "environment": {
                "description": "Environment to use. Used as part of the URL.",
                "enum": [
                    "vtexcommercestable"
                ],
                "default": "vtexcommercestable"
            }
        }
    }
],

The servers key contains an array of objects.

Authentication

Security schemes

Security schemes describe autentication types that are available in the API. You can check the all the available options in the Security Scheme Specification.

They should be added inside the components object.

The security schemes we use are:

"securitySchemes": {
    "appKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppKey",
        "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
    },
    "appToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppToken",
        "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
    },
    "VtexIdclientAutCookie": {
        "type": "apiKey",
        "in": "header",
        "name": "VtexIdclientAutCookie",
        "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours."
    }
}

Security requirement

If defined inside the Open API schema, the security object will define the required security schemes for all endpoints. This specifies that requests should have the X-VTEX-API-AppKey and X-VTEX-API-AppToken pair or VtexIdClientAutCookie as part of the request header.

If defined inside an endpoint object, the security object will define the security scheme for that specific endpoint.

The security object we use at VTEX is:

"security": [
        {
            "appKey": [],
            "appToken": []
        },
        {
            "VtexIdclientAutCookie": []
        }
    ]

Adding a new file

After creating a file for a new API reference in this repository, read this step-by-step to publish it on our Developer Portal.