The essential part of retrieving orders from BEES is the response from orders itself. The response contains all information of the order, such as the order number, the items that was purchased for that order as well as the information of the account that placed the order.

At first moment, the order response may shock given the size of the payload however the most important fields and properties will be covered below in more details.

Within the orders response, there are some properties that is designated as identifier. These key properties is explained in more details below:

BEES Identifiers

• Bees Account Id

  • The beesAccountId is the unique identifier of the establishment within BEES, is it generated once an account is created. It is important to highlight that the beesAccountId can differ from the account identification from the Partner's perspective, which for this case is referred to as vendor accountId.

• Order Number

  • The order number is the unique number of the order, it is generated once an order is created and can not be modified. Analog to the beesAccountId, the order number is an identifier generated by BEES and can differ from the order number within the partner’s erp. For the partner’s ERP order number it is necessary to populate the Vendor Order Number field.

Vendor Identifiers

• Vendor Id

  • The vendor identification is the unique number that refers to the partner within BEES, each partner will have a specific number and this number can not be modified.

• Vendor Account Id

  • The vendor AccountId field identifies and persists the unique identifier of the account from the Partner’s perspective. It is generated once the partner sends the account information through the Accounts entity.

• Vendor Order Number

  • The vendor Order Number also dictates the unique identification of the order based on the partner’s system. It can differ from Order number generated by BEES because in most cases once the order is created on the partner side, the partner’s system automatically generated a new order number;

  • It is important to emphasize that this field is passive, meaning that BEES wont be able to retrieve and populate it by its own, therefore, it is necessary that the Partner populate this field and update the order in BEES.

One important factor within Orders is the orders statuses. In BEES there are a variety of statuses that can be used to set the current situation for the order.

There is no order in BEES that exists without an status.

Within the response there are two fields that represents orders status, one is responsible to present the previous status of that order and the second field is the current status of the order.

A full list of available status can be found on the stoplight link below:

Within the Order Response, there are some properties which defines the key dates in which the order was created and updated. These fields can be used to audit when orders suffered a modification.

The three fields that are designed for this purpose is described below:

• Placement Date

  • The placement date persists the date in which the order was placed.

• Audit - Create At

  • This field persists the date in which the register of the order was created in the database of Orders. Therefore, although very similar, there may have a small different in seconds and milliseconds if comparing with the placement date.

• Audit - Update A

  • Updated at field is very straight forward and self explanatory. It states the date of the last time that the order was modified and that modification was persisted in the orders database.

The delivery element within the Orders response englobes all the necessary and key information corresponding to the delivery information for a specific order. Below the essential fields for the delivery element is described in more details:

• Delivery Date

  • This is the delivery date that the consumer selected when purchasing this specific order.

• Delivery Window Id

  • The delivery window identification is the unique identification that was configured in the Delivery Window entity to make that specific date available for users to select.

• Delivery Type

  • In BEES there are a different types of delivery, such as ALTERNATIVE and REGULAR, for most cases REGULAR is the type used.

• Delivery Center Id

  • The Delivery Center Identification that contains the products that the customer purchased from, this delivery center identification is the same delivery center that was populated for that customer through the Accounts entity.

• Delivered Date

  • This field indicates the real delivery date in which the order was delivered to the user. Although very similar, the Delivered Date is different from the Delivery Date field given that the first one states when the products were delivered and the second field, the Delivery Date that was explaning in the beginning, states the date in which the user selected to have their products delivered.

Another substantial element within the orders response is the Payment information. The payment information contains the payment method that the customer choose for that specific order. Within Payment element in Orders it is possible to have two properties that are described below:

• Payment Method

  • This properties defines the payment method in which the user selected when purchasing the order. It is important to notice that the options that the user will view during the checkout will be based on the payment method that was configured on the Accounts entity.

• Payment Term

  • This property may not appear in the order given that not all payment methods necessarily have a term. Therefore, for some payment method options, such as Bank Slip, this property will be presented in the response with the purpose of stating the term that the user selected for that specific payment method.

With the purpose of verifying the products that the customer purchase, within the orders response there the products purchased and all information related to them is consolidating within the items element.

Below, the main properties for the products within orders are described in detail:

• Key

  • Key is the unique identifier for that specific product in that specific order, each product within the orders will have a specific unique key. This key has the purpose of establish a single relationship for that product and can be used to make modifications such as modifying the quantity of that product without using a more broadly term such as sku and vendorItemId;

  • The key is generated once an order is created, and all products within the order will have a specific key. If the same product, such as the same vendorItemId and sku, is purchased in two different orders, they will have two distinct keys even though they are the same product.

• Item Quantity

  • This property is responsible to inform the amount of product that was purchased in that specific order.

• Item Metadata

  • Within the item elements there are several properties that is derived from the Items MS entity. A list of all information that orders pull information from the Items MS is listed below:

    • VendorItemId;

    • Sku;

    • Name;

    • Id;

    • Image;

    • Container;

    • Package;

    • Measure Unit;

    • Type of Unit.

• Summary Item

  • Within the items element, for a specific product that as purchase, it also contains the price information that populated in the Prices entity. The main properties of prices are described below:

    • Price:

      • The price of the product taking into consideration the quantity purchased. Therefore if an item is priced as 5$ and there are two items, the Price property will come at the end as 10$.

    • Original Price:

      • The price of a single product that was populated in the Price entity.

    • Subtotal:

      • The subtotal is sum of all prices for that product, not taking into consideration the taxes and discounts.

    • Total:

      • The total of the sum of all prices for that product taking into consideration the taxes and discounts for that product.

The Summary element within the Orders response dictates the summary of all prices accounts for all products purchased for as specific order. Therefore the following properties is also referred to order summary because it englobes all products:

• Subtotal

  • The order subtotal taking into consideration only the base price of products, without any taxes, charges nor discounts.

• Discount

  • The total amount of discounts applied to the order.

• Taxes

  • The sum of all taxes for that specific order.

• Charges

  • The sum of all charges for that specific order.

• Total

  • The total amount of that order, taking everything into consideration and accounts for the price of products, charges, taxes, discounts and any other fee.

Lastly, within the Order Response there are some other properties that can be found, however the most important one is described in details below:

• Channel

  • It is responsible to inform the origin of the orders, therefore, if the order was placed within BEES it will state if the order was placed via Web or Mobile application. If the order comes from other BEES Applications, such as BEES Force or BEES Grow it will have different channels.