Managing User Orders

API Reference

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

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

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}/restaurants/orders/v1/orders

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

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 the orders.

Retrieving New Orders From A Specific Store

API Reference

Use the GET stores/{storeId}/orders endpoint to retrieve a list of all the orders from a specific store 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}/restaurants/orders/v1/stores/{storeId}/orders

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 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}/restaurants/orders/v1/orders/status/sent

The system retrieves a JSON response with all the new orders of your store. 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 the orders.

Taking Orders

API Reference

Use the PUT stores/{storeId}/orders/{orderId}/take 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}/restaurants/orders/v1/stores/{storeId}/orders/{orderId}/take

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

Taking Orders with specific cooking time

API Reference

Use the PUT stores/{storeId}/orders/{orderId}/cooking_time/{cookingTime}/take endpoint to take orders that are in SENT status with a specific cooking time.

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}/restaurants/orders/v1/stores/{storeId}/orders/{orderId}/cooking_time/{cookingTime}/take

  • {COUNTRY_DOMAIN}: This is your Rappi Country Domain. See the list of Country Domains.
  • {storeId}: This is the identifier of your store.
  • {orderId}: This is the identifier of your order.
  • {cookingTime}: This is the new cooking time.

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.

Get QR Code of an Order

API Reference

Use the endpoint GET stores/{storeId}/orders/{orderId}/handoff to obtain the confirmation code and the QR code of the order.

Important

The QR code query can only be performed after the order has been created.

To obtain the QR code of the order, make a GET request to the following URL:

URL: https://{COUNTRY_DOMAIN}/restaurants/orders/v1/stores/{storeId}/orders/{orderId}/handoff

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

The system retrieves a JSON response that will contain the code, the QR, the order_id, and the store_id of the order. Consult the JSON response structure in the orders endpoint section of the API Reference.

Rejecting Orders

API Reference

Use the endpoint PUT stores/{storeId}/orders/{orderId}/cancel_type/{cancelType}/reject to reject an order.

Important

When you reject an order, the system changes its status to REJECT and the order is canceled.

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

URL: https://{COUNTRY_DOMAIN}/restaurants/orders/v1/stores/{storeId}/orders/{orderId}/cancel_type/{cancelType}/reject

  • {COUNTRY_DOMAIN}: This is your Rappi country domain. See the list of country domains.
  • {storeId}: This is your store identifier.
  • {orderId}: This is your order identifier.
  • {cancelType}: Corresponds to the cancellation type of your order.

List of Accepted Cancellation Types

In the following section, the cancellation types you can use to reject an order are described.

STORE_CLOSED

A cancellation for STORE_CLOSED is made when the restaurant is closed and cannot accept the order.

{ "description": "ORDER RECEIVED OUT OF HOURS", "additional_info": {} }

ITEM_STOCKOUT

A cancellation for ITEM_STOCKOUT is made when the restaurant does not have enough stock to complete the order.

{ "description": "Insufficient stock on some items", "additional_info": { "items": ["sku-123", "sku-23"], "identity_type": "RAPPI/SKU" } }

POS_OFFLINE

A cancellation for POS_OFFLINE is made when the integrator receives an order and cannot connect to the POS or Terminal.

{ "description": "The restaurant is having issues and cannot receive the order", "additional_info": {} }

POS_INTERNAL_ERROR

A cancellation for POS_INTERNAL_ERROR is made when there is an internal error in the POS or Terminal.

{ "description": "Technical issue in server", "additional_info": {} }

INTEGRATOR_ERROR

A cancellation for INTEGRATOR_ERROR is made when the integrator cannot process the order received by Rappi.

{ "description": "Error in converting the order from Rappi", "additional_info": {} }

DELIVERY_METHOD_NOT_SUPPORTED

A cancellation for DELIVERY_METHOD_NOT_SUPPORTED is made when the integrator receives an order and cannot process it because the delivery method is not supported.

{ "description": "Delivery method not supported", "additional_info": { "received_value": "pickup", "available_options": ["delivery", "marketplace", "pickup"] } }

ORDER_TOTAL_INCORRECT

A cancellation for ORDER_TOTAL_INCORRECT is made when the order total does not match the accounting in the integrator's systems.

{ "description": "Incorrect totals", "additional_info": { "received_value": 123.13, "expected_value": 130.23 } }

ORDER_CHARGES_INCORRECT

A cancellation for ORDER_CHARGES_INCORRECT is made when there is an error in the order charges, such as the service fee or delivery.

{ "description": "The delivery value is incorrect", "additional_info": {} }

ORDER_DISCOUNTS_INCORRECT

A cancellation for ORDER_DISCOUNTS_INCORRECT is made when there is an error in the discounts applied to the order.

{ "description": "The value of one or several discounts is incorrect", "additional_info": {} }

OUTSIDE_DELIVERY_AREA

A cancellation for OUTSIDE_DELIVERY_AREA is made when the integrator receives an order and needs to cancel it because the user is outside the delivery area.

{ "description": "Outside delivery area", "additional_info": {} }

ITEM_PRICE_INCORRECT

A cancellation for ITEM_PRICE_INCORRECT is made when the integrator needs to validate the unit prices of each product, but they do not match the prices in the POS.

{ "description": "The price of sku-23 is incorrect", "additional_info": { "offending_items": [ { "identifier": "sku-23", "identity_type": "RAPPI/SKU", "received_value": 123.13, "expected_value": 130.23 } ] } }

ITEM_NOT_FOUND

A cancellation for ITEM_NOT_FOUND is made when the integrator receives an order and some of the product identifiers are not recognized by the POS.

{ "description": "The products sku-123 and sku-23 were not found in the system", "additional_info": { "items": ["sku-123", "sku-23"], "identity_type": "RAPPI/SKU" } }

CUSTOMER_INFO_INCORRECT

A cancellation for CUSTOMER_INFO_INCORRECT is made when the integrator considers there are issues with the user's information.

{ "description": "Incorrect customer information", "additional_info": {} }