API ReferenceSDK & PluginsFAQsContact Us
API Reference
Start typing to search…

Orders Flow

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

Order Statuses

The order processing flow includes a total of 10 statuses, of which two —ready_to_ship and cancel— can be triggered directly by the merchant.

These statuses exist at the item level and can be retrieved using the GetOrderItems API. To check the status at the full order level, you can use the GetOrder API, where the status field will return an array containing all the item statuses associated with the order.

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.
  • canceled: 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. (We currently have a version 2.0 of this endpoint)
  • GetOrder (here): Retrieves the data of a specific order. (We currently have a version 2.0 of this endpoint)
  • 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. (Deprecated, this information can now be obtained through GetOrderItem)
  • GetTrackingCode (here): Retrieves the shipping tracking code, necessary for generating the label. (Deprecated, this information can now be obtained through GetOrderItem)
  • 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 has been registered and the order data stored, you must 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.
    This endpoint provides important fields such as OrderItemIds, PackageId, and GetTrackingCode, which will be used later in the flow.
    If any of these fields are not available when the order is created, you should retry the call until the data is populated.

  2. Next, you need to generate the shipping label using GetDocument.

  3. Finally, mark the product as ready for pickup using the SetStatusToReadyToShip API.
    Make sure to respect the promised shipping time (PromisedShippingTime) before handing over the package to the logistics provider.

  4. At this point, use the SetInvoicePDF API to upload the corresponding tax document.

If you have Fulfillment by Falabella (FBF):

  • FBF orders are identified by the attribute ShippingType = Own Warehouse.
  • It is crucial to recognize these orders to avoid reducing inventory from your own warehouse, as FBF inventory is stored in Falabella’s warehouses.
  • You can use GetOrder, GetOrderItems, or GetMultipleOrderItems to obtain more details about the order or its items if needed for your systems.
    You can track the order status evolution using GetOrders.
    Do not apply the SetStatusToReadyToShip API.
  • Similar to the Fulfillment by Seller flow, you can upload your invoices using the SetInvoicePDF API.
📘

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.