Managing User Orders#

API Reference

The Rappi API enables you to manage the orders that the users make using the Rappi application. The following sections describe the process to:

  • Manage the workflow and status of the user orders
  • Get user orders through API requests

Order Properties#

The following sections describe the properties of the orders, their different status, and the events that occur in the orders.

Order Status#

When a user creates an order, the order follows a specific flow since the moment the application starts processing it. The system triggers some of these status changes automatically whenever the order updates in the Rappi application, and the others must be updated manually.

The following table describes the different states that the order goes through:

Order Status Description Update Type Transitions From Transitions To
CREATED When a user creates an order in the Rappi application. Automatic N/A READY
READY When the application processes the order. Automatic CREATED SENT
SENT When the store sends the order to the user. Manual READY TAKEN

REJECTED

TIMEOUT
TAKEN When the store accepts the order. Manual READY READY_FOR_PICKUP
REJECTED When the store rejects the order. Manual READY N/A
TIMEOUT When neither the store nor Rappi, takes any action on the order. Automatic READY N/A
READY_FOR_PICKUP When the store has prepared the order. Automatic TAKEN N/A
WEBHOOK When the order is being processed via webhook Automatic N/A READY

By default, the system transitions the order from TAKEN to the READY_FOR_PICKUP automatically.

If the order is being processed via webhook, its initial status will be WEBHOOK

If you try to transition an order to an illegal state (for instance, reject an order already taken) it will end in an impossibility of iterate the order and returning an invalid transition message

You can request Rappi to manage this transition manually, considering the following:

  • When set to Automatic, Rappi transitions the status of the order based on the cooking time of the store and order delay records.

  • When set to Manual, you are required to call the POST orders/{orderId}/ready-for-pickup endpoint when the order is ready.

Important

Rappi recommends keeping this transition set to Automatic, to avoid any impact in the flow of your orders.

Order Events#

During the lifecycle of an order, the system indicates a series of events, and each of these events triggers a different action in the Rappi application.

For example, the system triggers an event when a courier is assigned to pick up an order at a store, and the event changes when the courier delivers this order to the customer.

The Rappi API enables you to retrieve the events' history of the orders.

The following table describes the events that can happen during the lifecycle of an order:

Order Event Event Description Transitions From Transitions To
taken_visible_order Occurs when:
- The order is assigned to the store inside Rappi, immediately after a successful take of an order.
- The courier is assigned to the order, in this case, Rappi also provides the ETA that it will take for the courier to arrive at the store.
N/A ready_for_pick_up

replace_storekeeper
replace_storekeeper Occurs when Rappi assigns a new courier the order, in this case, Rappi also provides the ETA that it will take for the courier to arrive at the store. taken_visible_order ready_for_pick_up
ready_for_pick_up Occurs when the store prepares the order and is ready for pickup. taken_visible_order

replace_storekeeper
domiciliary_in_store
domiciliary_in_store Occurs when the courier is at the store. ready_for_pick_up hand_to_domiciliary
hand_to_domiciliary Occurs when the store delivers the order to the courier. domiciliary_in_store arrive
arrive Occurs when the order arrives at the customer home. domiciliary_in_store close_order
close_order Occurs when the customer receives the order.. arrive N/A

Cancelation Events#

When a cancelation occurs in the Rappi platform, the system generates a cancelation event depending on the scenario and the circumstances of the cancelation.

The following table contains the existing cancelation events and their description:

Cancelation Event Occurs when:
cancel_by_user The user cancels an order.
canceled_with_charge The user cancels an order, and Rappi applies a cancelation fee to the user.
cancel_without_charges The user cancels an order with no charges to the user.
cancel_by_support Rappi Customer Support cancels the order.
cancel_by_support_with_charge Rappi Customer Support cancels the order, and Rappi applies a cancelation fee to the user.
cancel_by_application_user The ally cancels an order using the Customer application.
canceled_from_cms Rappi Customer Support cancels the order through the internal CMS tool.
canceled_by_fraud_automation Rappi cancels an order due to fraud detection.
canceled_store_closed Rappi cancels an order that the user made to a closed store.
cancel_by_sk_with_charge The courier service cancels the order, and Rappi applies a cancelation fee to the courier service.

Order Totals and Discounts#

Rappi enables you to configure discount campaigns by using the Rappi Growth application or The Partners Portal. You can apply discounts to individual products, stores, or configure special discount campaigns for a limited number of users that place orders.

Use the Rappi API to see the discounts applied to orders, discount totals, and price totals.

The following table describes the discounts information in the orders:

Discount Indicator Description
value Discount value in currency.
description Descriptive message explaining the discount.
title Discount name.
product_id Product ID if the discount applies to a product.
sku Product SKU if the discount applies to a product.
type Indicates the discount type.
raw_value The discount value can represent a percentage or a currency value depending on the value_type.
value_type The discount value type can be either value or percentage.
max_value Maximum value in currency to be discounted.
includes_toppings Indicates if the discount is subtracted from the product total with toppings or not.
percentage_by_rappi The percentage of the discount assumed by Rappi.
percentage_by_partners The percentage of the discount assumed by the partner.
amount_by_rappi Discount value in currency assumed by Rappi.
amount_by_partner Value of the discount in currency assumed by the partner.
discount_product_units Number of products to which the discount was applied.
discount_product_unit_value Discount value per product unit.

The following table describes the indicators for the order totals available:

Total Indicator Description
total_products The total of the products without discounts.
total_discounts The total of the discounts.
total_order The order total with discounts.
total_to_pay The remaining amount to pay in cash by the customer.
discount_by_support Discount applied to the customer by the Rappi support team.
charges The charges in the order.
shipping The order shipping fee.
service_fee The order service fee.
other_totals The additional totals of the order.
tip The tip to pay to the courier.
total_rappi_pay The amount paid with Rappi Pay.
total_rappi_credits The amount paid with Rappi Credits.

Delivery Methods#

Rappi enables you to configure different delivery methods for your orders.

This table describes the available delivery methods:

Delivery Method Description
delivery A Rappi courier delivers the order.
marketplace A courier from the store delivers the order.
pickup The customer picks up the order at the store.

Rappi always supports the delivery option for all of your stores, and you can choose to enable the marketplace and the pickup delivery methods.

You can configure these options at store level with your main Rappi point of contact.

Address Information#

Depending on the delivery methods of your stores, the API responses contain specific information.

The following table represents the common information shared between the different delivery methods.

Field Description
city The city of the address of the order.
neighborhood The neighborhood of the address of the order.
postal_code The postal code of the address of the order.
complement The address additional information.
complete_address The complete address of the order.

Marketplace Fields by Country#

The stores that have the marketplace delivery method enabled, receive additional information in their API responses.

The following table represents the additional information for each country.

Argentina Brazil Colombia Mexico Peru Other Countries
street_name street_shorcut complementary_street_without_meter street_name street_shorcut description
street_number street_name complete_main_street_number street_number street_name -
description street_number main_street_number_letter - street_number -
- federal_unit complementary_street_quadrant - - -
- - meter - - -
- - complementary_street_prefix - - -
- - complete_main_street - - -
- - main_street_type - - -
- - main_street_number_or_name - - -
- - complementary_street_letter - - -
- - main_street_prefix_letter - - -
- - main_street_prefix - - -
- - complete_complementary_street - - -
- - complementary_street_number - - -
- - complementary_street_prefix_letter - - -
- - main_street_quadrant - - -

Retrieving New Orders#

API Reference

Use the GET orders endpoint to retrieve a list of all the orders that are in READY status for further action.

Important

You can only retrieve new orders once. After you retrieve these orders, the system changes their status from READY to SENT.

To retrieve new orders:

Make a GET request to the following URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders

{COUNTRY_DOMAIN}: This is your Rappi Country Domain. See the list of Country Domains.

Note

To retrieve only the orders of a specific store, add the storeId parameter to your request.

The system retrieves a JSON response with all the new orders of your stores. Consult the JSON response structure in the orders endpoint section of the API Reference.

When you retrieve the list of your new orders, you can take, or reject the orders.

Retrieving New Orders Status SENT#

API Reference

Use the GET orders/status/sent endpoint to retrieve a list of all the orders that are in SENT.

Important

Only orders whose last status is SENT and that status has been updated within the time limit (10 minutes forward) will be retrieved.

Example:

If order change status to SENT at 14:00 of 12/10/2021, and use this enpoint at 14:07, it returns the order, because 14:07 - 10 minutes = 13:57 and the status change hour was at 14:00 then is bigger than 13:57.

Another example, if order change status to SENT at 14:00 of 12/10/2021, but use this enpoint at 17:30, it returns nothing, because 17:30 - 10 minutes = 17:20, and status change hour was at 14:00 then is lower than 17:20.

To retrieve new orders:

Make a GET request to the following URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/status/sent

{COUNTRY_DOMAIN}: This is your Rappi Country Domain. See the list of Country Domains.

Note

To retrieve only the orders of a specific store, add the storeId parameter to your request.

The system retrieves a JSON response with all the new orders of your stores. Consult the JSON response structure in the orders endpoint section of the API Reference.

When you retrieve the list of your new orders, you can take, or reject the orders.

Taking Orders#

API Reference

Use the PUT orders/{orderId}/take/{cookingTime} endpoint to take orders that are in SENT status.

Important

When you take an order, the system changes its status to TAKEN and the store starts its preparation.

Although it is unusual, if you get a status different to 200, use resilience patterns as retry; please use it along with exponential backoff to multiplicatively decrease the rate of the request.

To take an order make a PUT request to the following URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/take/

Note

You can modify the default cooking time of the order by entering a new cooking time at the end of the endpoint with the path parameter {cookingTime}: /orders/{orderId}/take/{cookingTime}.

The system retrieves a JSON object with the confirmation message "Order successfully taken".

Cooking Time - CT#

This function allows you to set the cooking time of an order when you take it in the POS.

What is cooking time?

Orders have three possible cooking times, which will be applied in the following order.

  • Predictive CT
  • CMS CT (with maximums and minimums)
  • CT set up in the integration core

How does the CT work?

The system goes through each CT in the order explained above to assign the order’s CT, and if it does not find one, it will continue with the next one until a CT is assigned.

Is it possible to change the CT?

Yes, you can change the CT with a value between the minimum and maximum set up in the integration core, and in case you choose a value out of the set up range, the system will select the minimum or maximum value set up in the integration core.

Rejecting Orders#

API Reference

Use the PUT orders/{orderId}/reject endpoint to reject orders that are in SENT status when:

  • The order contains invalid or unavailable items
  • The order contains items with an incorrect price

Important

Do not use this endpoint to limit the number of orders the store processes. If you reject several orders for a given store within a short time, Rappi disables the store in the application.

You can also disable items from the menu of the store when rejecting orders, by providing the items_sku or the items_id to the body of the request.

Note

The items you disable when rejecting an order can only be enabled again by Rappi Support. To see other ways to disable items, see the Manage Availability section of this portal.

To reject an order make a PUT request to the following URL, and add a JSON to the body of the request with the following objects.

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/reject

This is an example of the JSON object in the body of the request:

{
   "reason":"The order has invalid items"
}

Note

To disable items from the menu of the store, add the "items_sku" or the "items_ids" objects under "reason" in the JSON object.

The system retrieves a JSON object response with the confirmation message "Order successfully rejected".

Notify the Order is Ready for Pickup#

API Reference

If your stores have manual notification settings, use the POST orders/{orderId}/ready-for-pickup endpoint to notify the Rappi application when an order is ready for pickup.

To notify Rappi when an order is ready for pickup:

Make a POST request to the following URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/ready-for-pickup

The system retrieves a JSON response with the confirmation message "Order successfully updated".

Retrieving Order Events#

API Reference

You can retrieve the events of your order by using the GET orders/{orderId}/events endpoint.

To retrieve the events of your order:

Make a GET request to the following URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/events

The system retrieves a JSON response with the record of the events of your order.