Fetching marketplace information with the Orders API

The information contained in ecommerce invoices may vary according to business laws in each country. It is possible, for example, that you are required to include payment method information in case a sale is made through an intermediator.

VTEX stores this data during checkout and makes it available to sellers integrated with different types of marketplaces.

It is possible to see who the marketplace is by checking the order object with the Get order API request, in the affiliateId field, like in the example below.

{
  "emailTracked": "[email protected]",
  "approvedBy": null,
  "cancelledBy": null,
  "cancelReason": null,
  "orderId": "v5195004lux-01",
  "sequence": "502556",
  "marketplaceOrderId": "880102018018-01",
  "marketplaceServicesEndpoint": "http://oms.vtexinternal.com.br/api/oms?an=luxstore",
  "sellerOrderId": "00-v5195004lux-01",
  "origin": "Fulfillment",
  "affiliateId": "ABC",
  "salesChannel": "1",
  "merchantName": null,
  "status": "handling",
  "statusDescription": "Preparando Entrega",
  "value": 1160,
  "creationDate": "2019-01-28T20:09:43.8999580+00:00",
  "lastChange": "2019-02-06T20:46:11.7010747+00:00",
…

🚧

In case of sellers using the Multilevel Omnichannel Inventory feature, the affiliateId field identifies the marketplace in the level directly above it. This means that if a seller on the third level receives a fulfillment order made in a marketplace in the first level, the order’s affiliateId will refer to the second level marketplace.

Payment method information can be accessed in two different ways depending on the type of marketplace.

VTEX marketplaces

VTEX clients who are sellers of other VTEX clients can access intermediator payment method data in the order object, in the userPaymentInfo.paymentMethod array, within the invoiceData object. See the example below.

...
"invoiceData": {
    "userPaymentInfo": {
        "paymentMethod": [
            "creditCardPaymentGroup"
        ]
    }
}
...

The paymentMethod array includes strings which follow this pattern {payment-group-name}PaymentGroup. There are dozens of possible values, depending on the payment groups used by the marketplace. These are some examples:

  • "creditCardPaymentGroup"
  • "debitCardPaymentGroup"
  • "instantPaymentPaymentGroup"
  • "promissoryPaymentGroup"
  • "PayPalPlusPaymentGroup"
  • "OneBuyPaymentGroup"
  • "virtualDebitEloPaymentGroup"
  • "foodCardPaymentGroup"
  • "giftCardPaymentGroup"
  • "debitPaymentGroup"
  • "PaymentHubPaymentGroup"
  • "PagosNetPaymentGroup"
  • "bankInvoicePaymentGroup"
  • "PagosWebPaymentGroup"
  • "cardPromissoryPaymentGroup"
  • "SamsungPayPaymentGroup"

📘

For external sellers connected to VTEX marketplaces this data is also sent in the invoiceData object, in the format described above.

Natively integrated external marketplaces

VTEX provides native connectors that allow our clients to connect to external marketplaces. We store intermediator data and make it available to sellers integrating with:

  • B2W
  • Via Varejo
  • Magazine Luiza
  • Mercado Libre
  • Amazon
  • Carrefour
  • Netshoes
  • Centauro
  • Dafiti
  • Wish

In this scenario, marketplace payment method information is stored in the customData object in the orderForm data structure.

Fetching external marketplace payment method data

This is an example of what you might find in the customData object of the order object when using the Get order request:

{
  ...
  "customData": {
    "customApps": [
      {
        "id": "CN-Viavarejo-Integration",
        "fields": {
          "marketplacePaymentMethod": "credit_card"
        }
      }
    ]
  }
  ...
}

📘

The Checkout API allows integrators to create customizable fields in the shopping cart through the customData object. Their middleware can create extra fields in the orderForm data structure and set the value of each of these fields when placing an order, so that this additional information can be retrieved when fetching order details with the Orders API.

For orders made in marketplaces with native VTEX connectors, payment method will be available in the marketplacePaymentMethod field. These are the possible values for this field:

  • "credit_card"
  • "debit_card"
  • "bank_slip"
  • "bank_deposit"
  • "pix"
  • "digital_wallet"
  • "gift_card"
  • "virtual_credit"
  • "payment_method_not_informed"

Did this page help you?