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	`WEBHOOK` `READY`
`WEBHOOK`	When the order is being processed via webhook.	Automatic	`CREATED`	`READY` `SENT` `TAKEN` `REJECTED` `**TIMEOUT`
`READY`	When the application processes the order and is ready to be shipped to the store.	Automatic	`CREATED` `WEBHOOK`	`SENT` `TIMEOUT`
`SENT`	When the application confirms the receipt of the order by the store.	Manual-> Automatic->	`READY` `WEBHOOK`	`TAKEN` `REJECTED` `TIMEOUT`
`TAKEN`	When the store accepts the order.	Manual	`SENT` `**WEBHOOK`	`READY_FOR_PICKUP`
`REJECTED`	When the store rejects the order.	Manual	`SENT` `**WEBHOOK`	N/A
`TIMEOUT`	When neither the store nor Rappi, takes any action on the order. `***`	Automatic	`READY` `SENT` `**WEBHOOK`	N/A
`READY_FOR_PICKUP`	When the store has prepared the order.	Automatic `****`Manual	`TAKEN`	N/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. This will send a notification to the assigned courier; if none is assigned, it will speed up the assignment process.

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:

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.
`total_discount_by_partner`	The total amount in currency of discounts assumed by the partner.
`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/

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

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

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

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.

Upon making the first request:

If there is no courier assigned, the system will speed up the assignment process.
If there is a courier assigned, the system will send a notification to the assigned courier.
Depending on the current order status, the system will change the order status to READY_FOR_PICKUP.

Upon making the second request:

If there is a courier assigned, the system will send a notification to the assigned courier.

Important

To prevent misuse of the endpoint, we reserve the right to revoke access to clients who use it improperly. Therefore, after three requests, the system will stop executing additional actions, and any further attempts will be considered improper use of the endpoint.

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

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

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

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

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