Sign in

v1

latestOpenAPI 3.0.02026-07-141525155.4 KB
External Marketplace

New Order Integration

API to integrate an external channel's order into the VTEX plataform.

This process is asynchronous and a notification with the order's integration results will be sent to the endpoint specified in the connectorEndpoint field in App Template, if the connector uses our App template. The field connectorName is also optional for connectors that use our App Template and authenticate using the app's auth cookie. If the account is not informed in the URL host, it should also be defined as a query string parameter in the route: an={account}.

For a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete External Marketplace Integration Guide.

post/{accountName}.vtexcommercestable.com.br/api/order-integration/orders

Path parameters

accountNamestring required

Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.

Query parameters

anstring
Example:apiexamples

Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.

affiliateIdstring required
Example:MKP

ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace.

Headers

Content-Typestring required

Describes the type of the content being sent.

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Request body

allowFranchisesboolean required

Boolean indicating whether franchise accounts linked to the main seller should be considered. That is, if the order delivery pickup/SLA can belong to a franchise account, for example. This field is optional and defaults to false.

connectorEndpointstring

String with the connector's base endpoint that will receive notifications about the orders processing results, as well as status updates from VTEX OMS. This field accepts query strings. You can use the models below:

  • https://{{externalconnector}}.com

  • https://{{externalconnector.com}}/api/vtex if you additionaly want to send a relative URL with the endpoint.

This field is optional if the connector uses the App Template and authenticates on our request via VtexIdclientAutCookie.

It is required if the connector is native or does not use the App Template.

connectorNamestring

String with the identifier code of the connector responsible for the order.

This field is optional if the connector uses the App Template and authenticates on our request via VtexIdclientAutCookie.

It is required if the connector is native or does not use the App Template.

marketplaceOrderIdstring required

String that indicates the order's ID in the marketplace.

marketplaceOrderStatusstring required

Required field including a string with the order’s status in the marketplace. If you send an order with the status APPROVED to integrate, our service will automatically try to advance it’s status in VTEX after integrating it. This field accepts the following values:

  • new

  • approved

marketplacePaymentValueinteger required

Integer that indicates the order’s total value, which the marketplace will pay to the seller. It’s important to note that this value should include interest, if that’s the case. If the value is USD110.50, convert it to the format → 11050.

pickupAccountNamestring

String that indicates the name of the account responsible for the order’s pickup point. It is only required for pickup-in-point orders from franchise accounts, when franchise accounts allowFranchises is true and the order in question has a pickup-in-point delivery type. It is optional otherwise.

Example request

{
  "allowFranchises": false,
  "clientProfileData": {
    "corporateDocument": null,
    "corporateName": null,
    "corporatePhone": null,
    "document": "99999999999",
    "email": "email@email.com.br",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "99999999999",
    "stateInscription": null,
    "tradeName": null
  },
  "connectorEndpoint": "https://connector-endpoint.com/api/vtex",
  "connectorName": "SkyHub",
  "customData": {
    "customApps": [
      {
        "fields": {
          "marketplacePaymentMethod": "credit card"
        },
        "id": "marketplace-integration",
        "major": 1
      }
    ]
  },
  "invoiceData": {
    "userPaymentInfo": {
      "paymentMethods": [
        "creditCardPaymentGroup"
      ]
    }
  },
  "items": [
    {
      "id": "1",
      "price": 975,
      "quantity": 1
    }
  ],
  "marketplaceOrderId": "{{$guid}}",
  "marketplaceOrderStatus": "NEW",
  "marketplacePaymentValue": 3025,
  "pickupAccountName": "",
  "shippingData": {
    "isFob": true,
    "isMarketplaceFulfillment": true,
    "logisticsInfo": [
      {
        "deliveryIds": {
          "warehouseId": "AR1"
        },
        "lockTTL": "1d",
        "price": 2050,
        "selectedDeliveryChannel": "delivery",
        "selectedSla": "Express",
        "shippingEstimate": "2d"
      }
    ],
    "selectedAddresses": [
      {
        "addressId": "1",
        "addressType": "Residential",
        "city": "Curitiba",
        "complement": "101",
        "country": "BRA",
        "geoCoordinates": {
          "latitude": "-29.5",
          "longitude": "-45.8"
        },
        "neighborhood": "Portão",
        "number": "4125",
        "postalCode": "81020-235",
        "receiverName": "John Doe",
        "state": "PR",
        "street": "Rua Eduardo Carlos Pereira"
      }
    ]
  }
}

Response

OK

accountNamestring required

String that indicates which account made the request.

codestring required

String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the Response Codes section.

flowstring required

String containing the name of the flow responsible for the response. This field can contain the following values:

PlaceOrder: when integrating new orders

ApproveOrder: when approving existing orders

Unknown: when we’re not able to identify the flow

marketplaceOrderIdstring nullable required

String that indicates the order's ID in the marketplace.

messagestring required

String with a message explaining the code returned in the response.

operationIdstring nullable required

String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors.

successboolean required

Boolean that indicates if the response is successful or not.

Example response

{
  "accountName": "grocery1",
  "code": "SOI003",
  "errors": null,
  "fields": null,
  "flow": "PlaceOrder",
  "marketplaceOrderId": null,
  "message": "Order successfully enqueued",
  "operationId": null,
  "success": true
}