Managing User Orders#
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. 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 |
---|---|
unit_price_without_discount |
The base unit price of the item. Note: The information on subitems does not exist in this field. To see this data, look into each subitem. |
percentage_discount |
The discount percentage applied to the base price. |
unit_price_with_discount |
The final unit price after applying the discount. |
The following table describes the indicators for the order totals available:
Total Indicator | Description |
---|---|
total_products_without_discount |
The sum of prices without discounts of all the items and subitems in the order. |
total_products_with_discount |
The discount percentage applied to the base price. |
total_other_discounts |
The sum of all the discounts applied to the order that are not specific to a product. |
total_order |
The order total with discounts. |
total_to_pay |
The remaining amount to pay in cash by the customer. |
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#
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#
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#
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#
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#
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
{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#
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.