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 StatusDescriptionUpdate TypeTransitions FromTransitions To
CREATEDWhen a user creates an order in the Rappi application.AutomaticN/AWEBHOOK

READY
WEBHOOKWhen the order is being processed via webhook.AutomaticCREATED*READY

*SENT

**TAKEN

**REJECTED

**TIMEOUT
READYWhen the application processes the order and is ready to be shipped to the store.AutomaticCREATED

WEBHOOK
SENT

TIMEOUT
SENTWhen the application confirms the receipt of the order by the store.Manual->

Automatic->
READY

WEBHOOK
TAKEN

REJECTED

TIMEOUT
TAKENWhen the store accepts the order.ManualSENT

**WEBHOOK
READY_FOR_PICKUP
REJECTEDWhen the store rejects the order.ManualSENT

**WEBHOOK
N/A
TIMEOUTWhen neither the store nor Rappi, takes any action on the order. ***AutomaticREADY

SENT

**WEBHOOK
N/A
READY_FOR_PICKUPWhen the store has prepared the order.Automatic

****Manual
TAKENN/A

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

Orders in READY status can be queried at the GET orders?storeId={storeId} endpoint, *in case the order is being processed through webhook, it is not necessary to make the query unless that an error occurs in the process, since the order is sent to the store and the transition to the SENT status is carried out automatically.

When the orders are in the SENT status, they can be taken or rejected manually (ORDERS) , there is a time limit of 6 minutes to take or reject the order, otherwise it will transition to TIMEOUT status; **There are cases in which the ally has a webhook, but for some reason the response of the webhook is not successful, said order is considered as an order not received by the ally, Rappi keeps the order status in WEBHOOK , but it is possible to take or reject the order.

***Orders can be in the integration process for a maximum of 6 minutes, otherwise the order will transition to the TIMEOUT status.

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

****You can request Rappi to manage the transition to READY_FOR_PICKUP 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.

Important

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

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

Status order

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 EventEvent DescriptionTransitions FromTransitions To
taken_visible_orderOccurs 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/Aready_for_pick_up

replace_storekeeper
replace_storekeeperOccurs 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_orderready_for_pick_up
ready_for_pick_upOccurs when the store prepares the order and is ready for pickup.taken_visible_order

replace_storekeeper
domiciliary_in_store
domiciliary_in_storeOccurs when the courier is at the store.ready_for_pick_uphand_to_domiciliary
hand_to_domiciliaryOccurs when the store delivers the order to the courier.domiciliary_in_storearrive
arriveOccurs when the order arrives at the customer home.domiciliary_in_storeclose_order
close_orderOccurs when the customer receives the order..arriveN/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 EventOccurs when:
cancel_by_userThe user cancels an order.
canceled_with_chargeThe user cancels an order, and Rappi applies a cancelation fee to the user.
cancel_without_chargesThe user cancels an order with no charges to the user.
cancel_by_supportRappi Customer Support cancels the order.
cancel_by_support_with_chargeRappi Customer Support cancels the order, and Rappi applies a cancelation fee to the user.
cancel_by_application_userThe ally cancels an order using the Customer application.
canceled_from_cmsRappi Customer Support cancels the order through the internal CMS tool.
canceled_by_fraud_automationRappi cancels an order due to fraud detection.
canceled_store_closedRappi cancels an order that the user made to a closed store.
cancel_by_sk_with_chargeThe 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 IndicatorDescription
valueDiscount value in currency.
descriptionDescriptive message explaining the discount.
titleDiscount name.
product_idProduct ID if the discount applies to a product.
skuProduct SKU if the discount applies to a product.
typeIndicates the discount type.
raw_valueThe discount value can represent a percentage or a currency value depending on the value_type.
value_typeThe discount value type can be either value or percentage.
max_valueMaximum value in currency to be discounted.
includes_toppingsIndicates if the discount is subtracted from the product total with toppings or not.
percentage_by_rappiThe percentage of the discount assumed by Rappi.
percentage_by_partnersThe percentage of the discount assumed by the partner.
amount_by_rappiDiscount value in currency assumed by Rappi.
amount_by_partnerValue of the discount in currency assumed by the partner.
discount_product_unitsNumber of products to which the discount was applied.
discount_product_unit_valueDiscount value per product unit.

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

Total IndicatorDescription
total_productsThe total of the products without discounts.
total_discountsThe total of the discounts.
total_orderThe order total with discounts.
total_to_payThe remaining amount to pay in cash by the customer.
total_discount_by_partnerThe total amount in currency of discounts assumed by the partner.
discount_by_supportDiscount applied to the customer by the Rappi support team.
chargesThe charges in the order.
shippingThe order shipping fee.
service_feeThe order service fee.
other_totalsThe additional totals of the order.
tipThe tip to pay to the courier.
total_rappi_payThe amount paid with Rappi Pay.
total_rappi_creditsThe 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 MethodDescription
deliveryA Rappi courier delivers the order.
marketplaceA courier from the store delivers the order.
pickupThe 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.

FieldDescription
cityThe city of the address of the order.
neighborhoodThe neighborhood of the address of the order.
postal_codeThe postal code of the address of the order.
complementThe address additional information.
complete_addressThe 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.

ArgentinaBrazilColombiaMexicoPeruOther Countries
street_namestreet_shorcutcomplementary_street_without_meterstreet_namestreet_shorcutdescription
street_numberstreet_namecomplete_main_street_numberstreet_numberstreet_name-
descriptionstreet_numbermain_street_number_letter-street_number-
-federal_unitcomplementary_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.