v60

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-01361201.5 MB

User orders

Retrieve user order details

Lists all details from an order, through the perspective of the customer who placed the order.

You can only access information from orders created in the last two years, and that same period is valid for customers through My Account.

B2B Buyer Portal orders

You can use this endpoint to list orders by filtering with the following fields:

Text: texts in existing order fields, custom fields, and contact information fields.
Status: the current status of the orders you wish to list.
Creation date: the date the order was created.
The purchase agent ID: ID of the purchase agent that made the order.
Pending approval: You can also filter by orders which are pending approval (true) or orders which are not pending approval (false).

⚠️ When using the text field to filter by contact information, you must use the exact value of the field in the contact information. Partial matches are not supported. For example: If the user's first name is set to John Henry, you must write John Henry in the text field. Searching for John will return orders made by John, and not John Henry.

Note that this request should be made by an user or an appKey / appToken pair that is associated with the Call center operator role. Otherwise, it will return only orders from the same email informed in the clientEmail query parameter.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code 403 error. These are the applicable resources for this endpoint:

Product	Category	Resource
View My Contract Orders	My Account / OMS	ViewMyContractOrders
View My Org Unit Orders	My Account / OMS	ViewMyOrgUnitOrders
OMS	OMS access	View order

You can create a custom role with that resource or use one of the following predefined roles:

Role	Resource
Call center operator	View order
OMS - Read only	View order

❗ Assigning a predefined role to users or API keys usually grants permission to multiple License Manager resources. If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see Best practices for using API keys. To learn more about machine authentication at VTEX, see Authentication overview.

get/api/oms/user/orders/{orderId}

Path parameters

orderIdstring required

Example:1172452900788-01

Order ID is a unique code that identifies an order.

Query parameters

clientEmailstring

Example:customer@mail.com

Customer email. This field is exclusive for B2C users.

textstring

Example:Rio de Janeiro

Filter by text in existing order fields, custom fields, and contact information fields. This field is exclusive for B2B Buyer Portal users.

statusstring

Example:ready-for-handling

Order status. You can provide multiple values by repeating the query parameter. For example:

status=payment-pending&status=handling

This field is exclusive for B2B Buyer Portal users.

creation_datestring

Example:[2025-01-01T02:00:00.000Z TO 2025-04-08T23:59:59.999Z]

You can filter orders by creation date by concatenating the sufix creationDate with the range date in Timestamp format. This field accepts the value * for open ranges. For example:

creationDate:[* TO 2025-04-08T23:59:59.999Z]
creationDate:[2025-01-01T02:00:00.000Z TO *]

This field is exclusive for B2B Buyer Portal users.

purchase_agent_idstring

Example:848a994a-1b6b-4dbd-5555-0455af24e0f2

ID of the purchase agent. You can provide multiple values by repeating the query parameter. For example:

purchase_agent_id=848a994a-1b6b-4dbd-5555-0455af24e0f2&purchase_agent_id=848a994a-1b6b-4444-8498-0455af24e0f2

This field is exclusive for B2B Buyer Portal users.

my_pending_approvalsboolean

You can filter orders that are pending approval by the current user or by an organizational unit associated with the current user if it has ViewMyOrgUnitOrders permission. This field is exclusive for B2B Buyer Portal users.

Headers

Content-Typestring required

Type of the content being sent.

Acceptstring required

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

Response

orderIdstring required

Order ID is a unique code that identifies an order.

sequencestring required

Sequence is a six-digit string that follows the order ID. For example, in order 1268540501456-01 (501456), the sequence is 501456.

marketplaceOrderIdstring required

Marketplace order ID.

marketplaceServicesEndpointstring required

Marketplace services endpoint.

sellerOrderIdstring required

ID of the seller related to the order. It can be a VTEX seller or an external seller.

originstring required

Order's origin in the order flow, which can be Marketplace, Fulfillment or Chain.

affiliateIdstring required

Corresponds to the three-digit affiliate identification code of the seller responsible for the order.

salesChannelstring required

Sales channel (or trade policy) ID related to the order.

merchantNamestring required

Name of the merchant.

statusstring required

Order status.

statusDescriptionstring required

Deprecated. Status description which is displayed on the Admin panel. This field is obsolete and may not return any value.

valueinteger required

Order's total amount.

creationDatestring required

Order's creation date.

lastChangestring required

Order's last change date.

orderGroupstring required

Order's group ID.

marketplaceItemsstring[] required

Marketplace details object.

giftRegistryDatastring nullable required

Information about gift list, when it applies.

callCenterOperatorDatastring nullable required

Call center operator responsible for the order.

followUpEmailstring required

Email of the store's employee responsible for managing the order.

lastMessagestring nullable required

Last sent transactional message.

hostnamestring required

Account Hostname registered in License Manager.

invoiceDataobject nullable required

Information pertinent to the order's invoice.

openTextFieldstring nullable required

Optional field with order's additional information. This field must be filled in using the following format:


{
    "fieldExample": "ValueExample"
  }

roundingErrorinteger required

Rounding error total amount, if it applies. For example, in orders with a discount over non-integer multiplier items, the rounding price is performed per item, not after the sum of all items. That can cause a difference in the total discount amount, which is informed in this field.

orderFormIdstring required

Order form ID.

commercialConditionDatastring nullable required

Information about commercial conditions.

isCompletedboolean required

When set as true, the order's payment has been settled, and when set as false, it has not been settled yet.

customDatastring nullable required

Custom information in the order. This field is useful for storing data not included in other fields, for example, a message for a gift or a name to be printed in a shirt.

allowCancellationboolean required

When set as true, the order can be canceled, and when set as false, it is no longer possible to cancel the order.

allowEditionboolean required

When set as true, the order can be edited, and when set as false, it is no longer possible to edit the order.

isCheckedInboolean required

This field is set true when the order was made via inStore and false when it was not.

authorizedDatestring required

Authorized order date.

invoicedDatestring nullable required

Order's invoice date.

cancelReasonstring nullable required

Reason for order cancellation.

checkedInPickupPointIdstring required

If the field isCheckedIn is set as true, the checkedInPickupPointId will retrieve the ID of the physical store where the order was made.

Example response

{
  "orderId": "v502556llux-01",
  "sequence": "502556",
  "marketplaceOrderId": "",
  "marketplaceServicesEndpoint": "http://oms.vtexinternal.com.br/api/oms?an=luxstore",
  "sellerOrderId": "00-v502556llux-01",
  "origin": "Marketplace",
  "affiliateId": "",
  "salesChannel": "1",
  "merchantName": "luxstore",
  "status": "handling",
  "statusDescription": "Preparando Entrega",
  "value": 1160,
  "creationDate": "2019-01-28T20:09:43.899958+00:00",
  "lastChange": "2019-02-06T20:46:11.7010747+00:00",
  "orderGroup": "v502556lspt",
  "totals": [
    {
      "id": "Items",
      "name": "Total dos Itens",
      "value": 3290
    },
    {
      "id": "Discounts",
      "name": "Total dos Descontos",
      "value": 0
    },
    {
      "id": "Shipping",
      "name": "Total do Frete",
      "value": 1160
    },
    {
      "id": "Tax",
      "name": "Total da Taxa",
      "value": 0
    },
    {
      "id": "Change",
      "name": "Total das mudanças",
      "value": -3290
    }
  ],
  "items": [
    {
      "uniqueId": "87F0945396994B349158C7D9C9941442",
      "id": "1234568358",
      "productId": "9429485",
      "ean": null,
      "lockId": "00-v502556llux-01",
      "itemAttachment": {
        "content": {},
        "name": null
      },
      "attachments": [],
      "quantity": 1,
      "seller": "1",
      "name": "Bay Max L",
      "refId": "BIGHEROBML",
      "price": 3290,
      "listPrice": 3290,
      "manualPrice": null,
      "priceTags": [],
      "imageUrl": "http://luxstore.vteximg.com.br/arquivos/ids/159263-55-55/image-cc1aed75cbfa424a85a94900be3eacec.jpg?v=636795432619830000",
      "detailUrl": "/bay-max-9429485/p",
      "components": [],
      "bundleItems": [],
      "params": [],
      "offerings": [],
      "attachmentOfferings": [
        {
          "name": "vtex.subscription.weekly",
          "required": false,
          "schema": {
            "vtex.subscription.key.frequency": {
              "MaximumNumberOfCharacters": 7,
              "Domain": [
                " 1 week",
                " 2 week",
                " 3 week",
                " 4 week"
              ]
            }
          }
        }
      ],
      "sellerSku": "1234568358",
      "priceValidUntil": null,
      "commission": 0,
      "tax": 0,
      "preSaleDate": null,
      "additionalInfo": {
        "brandName": "VTEX",
        "brandId": "2000023",
        "categoriesIds": "/1/",
        "productClusterId": "135,142",
        "commercialConditionId": "5",
        "dimension": {
          "cubicweight": 0.7031,
          "height": 15,
          "length": 15,
          "weight": 15,
          "width": 15
        },
        "offeringInfo": null,
        "offeringType": null,
        "offeringTypeId": null
      },
      "measurementUnit": "un",
      "unitMultiplier": 1,
      "sellingPrice": 3290,
      "isGift": false,
      "shippingPrice": null,
      "rewardValue": 0,
      "freightCommission": 0,
      "priceDefinitions": {
        "sellingPrices": [
          {
            "value": 99,
            "quantity": 1
          }
        ],
        "calculatedSellingPrice": 99,
        "total": 99
      },
      "taxCode": null,
      "parentItemIndex": null,
      "parentAssemblyBinding": null,
      "callCenterOperator": "callCenterOp5473869",
      "serialNumbers": "3",
      "assemblies": [],
      "costPrice": 52
    }
  ],
  "marketplaceItems": [],
  "clientProfileData": {
    "id": "clientProfileData",
    "email": "rodrigo.cunha@vtex.com.br",
    "firstName": "Rodrigo",
    "lastName": "Cunha",
    "documentType": "cpf",
    "document": "11047867702",
    "phone": "+5521972321094",
    "corporateName": null,
    "tradeName": null,
    "corporateDocument": null,
    "stateInscription": null,
    "corporatePhone": null,
    "isCorporate": false,
    "userProfileId": "5a3692de-358a-4bea-8885-044bce33bb93",
    "customerClass": null
  },
  "giftRegistryData": null,
  "marketingData": {
    "id": "marketingData",
    "utmSource": "fb",
    "utmPartner": "utm partner",
    "utmMedium": "utm medium",
    "utmCampaign": "christmas",
    "coupon": "sale",
    "utmiCampaign": " ",
    "utmipage": " ",
    "utmiPart": " ",
    "marketingTags": [
      "vtex-subscription"
    ]
  },
  "ratesAndBenefitsData": {
    "id": "ratesAndBenefitsData",
    "rateAndBenefitsIdentifiers": []
  },
  "shippingData": {
    "id": "shippingData",
    "address": {
      "addressType": "residential",
      "receiverName": "Rodrigo Cunha",
      "addressId": "-1425945657910",
      "versionId": "e9c3bec2-125d-4b96-a021-316c3aa9f14f",
      "entityId": "eabfb564-99d6-40d8-bd6c-bddbd4990aad",
      "postalCode": "22250-040",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "country": "BRA",
      "street": "Praia de Botafogo",
      "number": "518",
      "neighborhood": "Botafogo",
      "complement": "10",
      "reference": null,
      "geoCoordinates": []
    },
    "logisticsInfo": [
      {
        "itemIndex": 0,
        "selectedSla": "Normal",
        "lockTTL": "10d",
        "price": 1160,
        "listPrice": 1160,
        "sellingPrice": 1160,
        "deliveryWindow": null,
        "deliveryCompany": "Todos os CEPS",
        "shippingEstimate": "5bd",
        "shippingEstimateDate": "2019-02-04T20:33:46.4595004+00:00",
        "slas": [
          {
            "id": "Normal",
            "name": "Normal",
            "shippingEstimate": "5bd",
            "deliveryWindow": null,
            "price": 1160,
            "deliveryChannel": "delivery",
            "pickupStoreInfo": {
              "additionalInfo": null,
              "address": null,
              "dockId": null,
              "friendlyName": null,
              "isPickupStore": false
            },
            "polygonName": "region13",
            "lockTTL": "12d",
            "pickupPointId": "1_VTEX-RJ",
            "transitTime": "0d",
            "pickupDistance": 29.861602783203125
          },
          {
            "id": "Expressa",
            "name": "Expressa",
            "shippingEstimate": "5bd",
            "deliveryWindow": null,
            "price": 1160,
            "deliveryChannel": "delivery",
            "pickupStoreInfo": {
              "additionalInfo": null,
              "address": null,
              "dockId": null,
              "friendlyName": null,
              "isPickupStore": false
            },
            "polygonName": "region13",
            "lockTTL": "12d",
            "pickupPointId": "1_VTEX-RJ",
            "transitTime": "0d",
            "pickupDistance": 29.861602783203125
          },
          {
            "id": "Quebra Kit",
            "name": "Quebra Kit",
            "shippingEstimate": "2bd",
            "deliveryWindow": null,
            "price": 1392,
            "deliveryChannel": "delivery",
            "pickupStoreInfo": {
              "additionalInfo": null,
              "address": null,
              "dockId": null,
              "friendlyName": null,
              "isPickupStore": false
            },
            "polygonName": "region13",
            "lockTTL": "12d",
            "pickupPointId": "1_VTEX-RJ",
            "transitTime": "0d",
            "pickupDistance": 29.861602783203125
          },
          {
            "id": "Sob Encomenda",
            "name": "Sob Encomenda",
            "shippingEstimate": "32bd",
            "deliveryWindow": null,
            "price": 1392,
            "deliveryChannel": "delivery",
            "pickupStoreInfo": {
              "additionalInfo": null,
              "address": null,
              "dockId": null,
              "friendlyName": null,
              "isPickupStore": false
            },
            "polygonName": "region13",
            "lockTTL": "12d",
            "pickupPointId": "1_VTEX-RJ",
            "transitTime": "0d",
            "pickupDistance": 29.861602783203125
          }
        ],
        "shipsTo": [
          "BRA"
        ],
        "deliveryIds": [
          {
            "courierId": "197a56f",
            "courierName": "Todos os CEPS",
            "dockId": "1",
            "quantity": 1,
            "warehouseId": "1_1",
            "accountCarrierName": "recorrenciaqa",
            "kitItemDetails": []
          }
        ],
        "deliveryChannels": [
          {
            "id": "delivery",
            "stockBalance": 0
          }
        ],
        "deliveryChannel": "delivery",
        "pickupStoreInfo": {
          "additionalInfo": null,
          "address": null,
          "dockId": null,
          "friendlyName": null,
          "isPickupStore": false
        },
        "addressId": "-1425945657910",
        "versionId": "e9c3bec2-125d-4b96-a021-316c3aa9f14f",
        "entityId": "eabfb564-99d6-40d8-bd6c-bddbd4990aad",
        "polygonName": "region56",
        "pickupPointId": "1_VTEX-RJ",
        "transitTime": "3d"
      }
    ],
    "trackingHints": null,
    "selectedAddresses": [
      {
        "addressId": "-1425945657910",
        "versionId": "e9c3bec2-125d-4b96-a021-316c3aa9f14f",
        "entityId": "eabfb564-99d6-40d8-bd6c-bddbd4990aad",
        "addressType": "residential",
        "receiverName": "Rodrigo Cunha",
        "street": "Praia de Botafogo",
        "number": "518",
        "complement": "10",
        "neighborhood": "Botafogo",
        "postalCode": "22250-040",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "country": "BRA",
        "reference": null,
        "geoCoordinates": []
      }
    ]
  },
  "paymentData": {
    "transactions": [
      {
        "isActive": true,
        "transactionId": "418213DE29634837A63DD693A937A696",
        "merchantName": "luxstore",
        "payments": [
          {
            "id": "D3DEECAB3C6C4B9EAF8EF4C1FE062FF3",
            "paymentSystem": "6",
            "paymentSystemName": "Boleto Bancário",
            "value": 4450,
            "installments": 1,
            "referenceValue": 4450,
            "cardHolder": null,
            "cardNumber": null,
            "firstDigits": null,
            "lastDigits": null,
            "cvv2": null,
            "expireMonth": null,
            "expireYear": null,
            "url": "https://luxstore.vtexpayments.com.br:443/BankIssuedInvoice/Transaction/418213DE29634837A63DD693A937A696/Payment/D3DEECAB3C6C4B9EAF8EF4C1FE062FF3/Installment/{Installment}",
            "giftCardId": null,
            "giftCardName": null,
            "giftCardCaption": null,
            "redemptionCode": null,
            "group": "bankInvoice",
            "tid": null,
            "dueDate": "2019-02-02",
            "connectorResponses": {
              "Tid": "94857956",
              "ReturnCode": "200",
              "Message": "logMessage",
              "authId": "857956"
            },
            "giftCardProvider": "presentCard",
            "giftCardAsDiscount": false,
            "koinUrl": "koinURL",
            "accountId": "5BC5C6B417FE432AB971B1D399F190C9",
            "parentAccountId": "5BC5C6B417FE432AB971B1D399F190C9",
            "bankIssuedInvoiceIdentificationNumber": "23797770100000019003099260100022107500729050",
            "bankIssuedInvoiceIdentificationNumberFormatted": "32534.95739 75945.24534 54395.734214 5",
            "bankIssuedInvoiceBarCodeNumber": "325349573975945245345439573421443986734065",
            "bankIssuedInvoiceBarCodeType": "i25",
            "billingAddress": {}
          }
        ]
      }
    ]
  },
  "packageAttachment": {
    "packages": []
  },
  "sellers": [
    {
      "id": "1",
      "name": "Lux Store",
      "logo": "https://sellersLogo/images.png",
      "fulfillmentEndpoint": "http://fulfillment.vtexcommerce.com.br/api/fulfillment?an=accountName"
    }
  ],
  "callCenterOperatorData": null,
  "followUpEmail": "7bf3a59bbc56402c810bda9521ba449e@ct.vtex.com.br",
  "lastMessage": null,
  "hostname": "luxstore",
  "invoiceData": null,
  "changesAttachment": {
    "id": "changeAttachment",
    "changesData": [
      {
        "reason": "Blah",
        "discountValue": 3290,
        "incrementValue": 0,
        "itemsAdded": [],
        "itemsRemoved": [
          {
            "id": "1234568358",
            "name": "Bay Max L",
            "quantity": 1,
            "price": 3290,
            "unitMultiplier": null
          }
        ],
        "receipt": {
          "date": "2019-02-06T20:46:04.4003606+00:00",
          "orderId": "v502556llux-01",
          "receipt": "029f9ab8-751a-4b1e-bf81-7dd25d14b49b"
        }
      }
    ]
  },
  "openTextField": null,
  "roundingError": 0,
  "orderFormId": "caae7471333e403f959fa5fd66951340",
  "commercialConditionData": null,
  "isCompleted": true,
  "customData": null,
  "storePreferencesData": {
    "countryCode": "BRA",
    "currencyCode": "BRL",
    "currencyFormatInfo": {
      "CurrencyDecimalDigits": 2,
      "CurrencyDecimalSeparator": ",",
      "CurrencyGroupSeparator": ".",
      "CurrencyGroupSize": 3,
      "StartsWithCurrencySymbol": true
    },
    "currencyLocale": 1046,
    "currencySymbol": "R$",
    "timeZone": "E. South America Standard Time"
  },
  "allowCancellation": true,
  "allowEdition": false,
  "isCheckedIn": false,
  "marketplace": {
    "baseURL": "http://oms.vtexinternal.com.br/api/oms?an=luxstore",
    "isCertified": null,
    "name": "luxstore"
  },
  "authorizedDate": "2019-01-28T20:33:04+00:00",
  "invoicedDate": null,
  "cancelReason": "The size was too big.",
  "itemMetadata": {
    "Items": [
      {
        "Id": "18",
        "Seller": "1",
        "Name": "Cat food",
        "SkuName": "Cat food",
        "ProductId": "6",
        "RefId": "105",
        "Ean": "43673557",
        "ImageUrl": "http://store.vteximg.com.br/ids/155392-55-55/AlconKOI.jpg?v=635918402228600000",
        "DetailUrl": "/catfood/p",
        "AssemblyOptions": [
          {
            "Id": "vtex.subscription.plan-ana",
            "Name": "vtex.subscription.plan-ana",
            "Required": false,
            "InputValues": {
              "vtex.subscription.key.frequency": {
                "MaximumNumberOfCharacters": 8,
                "Domain": [
                  "4 month",
                  "1 month"
                ]
              }
            },
            "Composition": {}
          }
        ]
      }
    ]
  },
  "subscriptionData": {
    "SubscriptionGroupId": "A64AC73C0FB8693A7ADB4AC69CA4FD5F",
    "Subscriptions": [
      {
        "ExecutionCount": 724,
        "PriceAtSubscriptionDate": 100,
        "ItemIndex": 0,
        "Plan": {
          "type": "RECURRING_PAYMENT",
          "frequency": {
            "periodicity": "DAILY",
            "interval": 1
          },
          "validity": {
            "begin": "2022-01-10T00:00:00.0000000+00:00",
            "end": "2024-02-03T00:00:00.0000000+00:00"
          }
        }
      }
    ]
  },
  "taxData": {
    "areTaxesDesignatedByMarketplace": true,
    "taxInfoCollection": [
      {
        "itemIndex": 0,
        "sku": "COLOCAR_O_SKUID",
        "priceTags": [
          {
            "isPercentual": false,
            "name": "Taxes (Magazine Luisa)",
            "rawValue": "COLOCAR_O_VALOR_SEM_DECIMAL"
          }
        ]
      }
    ]
  },
  "checkedInPickupPointId": "storeNameExample_901",
  "cancellationData": {
    "RequestedByUser": true,
    "RequestedBySystem": false,
    "RequestedBySellerNotification": false,
    "RequestedByPaymentNotification": false,
    "Reason": "Item was too big in the client.",
    "CancellationDate": "2022-10--05T15:40:33"
  },
  "clientPreferencesData": {
    "locale": "en-US",
    "optinNewsLetter": false
  }
}