API ReferenceSDK & PluginsFAQsContact Us
API Reference

Flow Orders

To operate with our APIs, it is crucial that you understand the sales flow.

Order Statuses

The order processing process includes a total of 10 statuses, of which two ("ready_to_ship" and "Cancel") can be triggered by the seller. To detect each of these statuses, you can use the webhook or the GetOrders API (here).

The available statuses are as follows:

Purchase Statuses

  • Pending: Initial state where the order is created. This can be obtained in the first GetOrders (here) or GetOrder (here) call, or from the order creation notification in the webhook event (here).
  • Ready_To_Ship: Seller confirms they are ready to ship the product (order). From this state, the order cannot be canceled by either the seller or the customer, and the reserved stock is deducted from the available stock.
  • Shipped: The seller hands the package to the logistics operator or Falabella logistics. This can be pickup or delivery at a pickup point. We register this state internally to measure the seller’s first-mile delivery compliance (OTS = On Time Seller), used to measure the Fplus level (which ensures responsibility transfer to the carrier based on the promised shipping date).
  • Delivered: The seller learns via Webhook or GetOrders API that the customer has received the order. This status triggers payment to the seller.
  • Failed: If after 3 delivery attempts (this may vary depending on the carrier), the order cannot be delivered to the customer, the order is marked as failed.
  • Cancel: Terminal state of an order. This can be triggered by the seller, customer, agents, or logistics provider.

Post-Sale Statuses

  • Return_Ship_by_Customer: Transitional status triggered when a product is returned by the customer to an office, authorized transport, or Falabella holding stores (this is triggered when the customer delivers the product, not when the return is initiated).
  • Return_awaiting_for_approval: Transitional status. In this state, the seller must accept or reject the return. If the seller rejects the request, a dispute process begins. The seller has 72 hours to appeal before the return is automatically accepted.
  • Returned: When the seller’s dispute is rejected, or the seller does not initiate a dispute or accepts the return.
  • Returned_Rejected: Falabella accepts the seller's dispute process.

APIs

Order Flow APIs:

  • GetOrders (here): Retrieves orders from a selected date to the current date and time, allowing filters like a specific "status" (e.g., pending), among others.
  • GetOrder (here): Retrieves the data of a specific order.
  • GetOrderItems (here): Retrieves the items of a specific order.
  • GetMultipleOrderItems (here): Retrieves the items of an array of orders.
  • SetStatusToPackedByMarketplace (here): Marks an item as packed and returns the carrier’s name and the internal identifier of the package or bundle in which the item should be packed.
  • GetTrackingCode (here): Retrieves the shipping tracking code, necessary for generating the label.
  • GetDocument (here): Retrieves a label. If the seller is subscribed to PDF labels, the response mimetype will be "application/pdf"; if subscribed to ZPL labels, the mimetype will be "text/plain". The mimetype indicates the necessary decoding type for the BASE64 response (attribute file).
  • SetStatusToReadyToShip (here): Marks an item as ready to ship.
  • SetInvoicePDF (here): Uploads a tax document.
  • SetStatusToCanceled (here): Cancels the order (package) containing the requested item, only if it is in the "pending" state.

Calculating the Total Sale Value

📘

Calculating the total sale value for tax documents

To calculate the total value of an order, you must consider the following:

  1. Have the OrderId for which you want to calculate the total value.
  2. Use GetOrderItems or GetMultipleOrderItems to retrieve the order details.
  3. The final amount with which you should issue the tax document, which corresponds to the "Grand Total" field in Falabella Seller Center, will be the sum of the PaidPrice and ShippingAmount fields for each product in the order.

It's important to consider this calculation as the proper method to obtain the final sale value. If your business has special promotions, the amount from the Price field in the GetOrder or GetOrders APIs could differ, potentially causing issues with tax document generation.

API GetOrderItems

API GetMultipleOrderItems

Using APIs to Generate a Purchase Flow

How to know if a sale or status change has occurred?

There are two methods to know if a sale has been made or if a status has changed. Ideally, both methods should be used complementarily:

  • Using WebHook: Configure the events associated with "orders," so that each time a sale is made, you will be notified at the indicated URL. It is recommended to use GetOrders afterward to register the order data.
  • Using GetOrders API: You can create a cron job that queries the API at regular intervals, applying status filters to retrieve orders with a "Pending" status, which are those that have not yet been processed. Then store key order data like the OrderID. You can also filter by other statuses to track orders (Pending, Ready_To_Ship, Shipped, Delivered, Failed, and Canceled).

What to do once you know a sale has occurred?

If you use Fulfillment by Seller

  1. Once a new sale is registered and the order data is stored, use the GetOrderItems method to retrieve the items associated with the order. If you are working with a batch of orders, remember you can use GetMultipleOrderItems. From this endpoint, important fields such as OrderItemIds will be used as input for the packaging or tax document upload process.
  2. Once the products are packed, use the SetStatusToPackedByMarketplace API to obtain the PackageId, which will be used later in the process of marking the package as ready for shipment.
  3. Next, retrieve the shipping tracking number using the GetTrackingCode API.
  4. Then, generate the label using GetDocument.
  5. Finally, mark the product as ready for pickup using the SetStatusToReadyToShip API. The reserved stock will be deducted from the stock via the GetProducts API once it reaches this state.
  6. From this point, use the SetInvoicePDF API to upload the respective tax document.

If you use Fulfillment by Falabella

  • FBF orders can be identified with the attribute ShippingType = Own Warehouse.
  • Recognizing these orders is vital to avoid reducing inventory from your own warehouse, as the FBF inventory is stored at Falabella warehouses.
  • No API actions are needed. You can use GetOrder, GetOrderItems, or GetMultipleOrderItems to obtain more details about the order or the associated items if required for your systems. You can track the order’s status changes using GetOrders.

📘

Status Tracking

You can track status changes by enabling the onOrderItemsStatusChanged event in the webhook or using the GetOrders API.

How can I cancel an order?

Orders can only be canceled in the pending state. Both the customer and the seller can cancel the product. If the cancellation is made by the seller, a penalty will be applied.

Order Flow

You can click on the image to view it, or right-click and select "Save As" to download it and keep the image in its original resolution.