Skip to main content
API docs by Redocly

Docs API Cargo | By Rappi (3.0)

Download OpenAPI specification:Download

This API lets you do everything Cargo By Rappi can do — create and track deliveries, manage stores and users — without opening the Cargo portal. This page is the reference for every public endpoint; the guide below is the fastest path from zero to a delivered order.

Cargo Portal

Everything here can also be done in the portal, which is handy for browsing orders and configuration while you build your integration:

Getting started — the integration in 6 steps

A minimal integration is really just one call (order-create). The steps below add the pieces most partners want, in the order you'll build them.

Step 1 — Authenticate with your user-token

Every request is authenticated with an API key sent in the user-token HTTP header. There is no login/OAuth flow: your KAM (Key Account Manager) at Rappi Cargo provisions the token for your account. Send it on every call; a missing or invalid token returns 401 Unauthorized.

Tip: use the DEV server (see the "Servers" dropdown) while integrating, then switch the base URL to your country's production server when you go live. The token is environment-specific.

Step 2 — Register your store (picking point)

An order always starts at a picking point — the store the courier picks up from. Create your stores once via picking-point create (or in the portal). You'll reference a store in each order either by Cargo's picking_point_id or by your own external_picking_point_id. You only do this when your stores change, not per order.

Step 3 — (Optional) Validate the delivery before creating it

Call Order-validate to check whether an order could be created, without creating it. It runs the same coverage/time/availability checks as create and returns the estimated ETA and trip distance. Many partners call it at checkout to show an ETA or to block an order Rappi can't deliver. It's optional — skip it if you don't need the preview.

Step 4 — Create the order

Order-create is the one required call. The request is built around action points — the ordered stops the courier makes. The essentials:

  • Provide at least 2 action points, including at least one STORE and one CLIENT. A PICK_UP at the store then a DROP_OFF at the client is the typical shape.
  • On each action point send a products array. On PICK_UP points list what's collected there; on DROP_OFF points send an empty [] (the courier drops off everything gathered so far). The field must be present on every action point — omitting it fails validation.
  • Send a unique order_id (your identifier). It doubles as the idempotency key, so retries won't create duplicate orders.
  • Set total_value to the full amount the client pays. For CASH orders this is exactly what the courier collects (plus tip).

See the "Create an order" examples for ready-to-send request bodies (simple, multi-store, and inverse/return deliveries).

To repeat a delivery you already created — the same stores, client and products — you don't have to rebuild the payload: order-creation-body returns the original request body ready to be sent back to order-create as a duplicate.

Step 5 — Track the order status

Use Order-status to follow the order. Two options: poll the endpoint, or (recommended) have Cargo push updates to a webhook — give your KAM the URL (and any header) and you'll receive a call on every status change. Status events can repeat (e.g. multiple on_the_route events across action points).

Step 6 — Cancel when needed

Order-cancel cancels an order via API. It only works while the order is in created, in_progress or in_store; once it's on_the_route (the courier holds the products) it can no longer be canceled this way.

Pre-flight checklist — avoid the common mistakes

Verify these before going live; each is a frequent cause of rejected or failed orders:

  • Coordinates: if you send lat/lng, use between 2 and 9 decimals. If you don't, make sure the address is precise enough to geocode.
  • Phone numbers — no country code: send the client and store phone without the country indicator (that goes in phone_country_code).
  • Phone length: the number must have the correct mobile length for the country, or the order is rejected.
  • Mobile only, no landlines: Cargo reaches the client via SMS and WhatsApp, so landlines are not accepted.
  • Address complement: always include an apartment/office/building detail. A bare address often means the courier can't find the client and the order gets canceled.
  • At least 2 action points: one STORE and one CLIENT.
  • total_value is the full charge: for CASH orders it must equal exactly what the courier collects — include surcharges, not just the sum of product prices.

Order V3

Create an order

This endpoint allows you to create an order in the Rappi Cargo system and request a driver.

The endpoint is built around action points. Each action is a stop that the driver will make to fulfill the order, making it possible to create many order variations sucha as the ones presented in the examples. Every order must have at least one action point of type STORE and at least one action point of type CLIENT. Whenever an action point is of type DROP_OFF the driver will deliver all the products that he has picked up until that point.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
total_value
required
number >= 1

Required. Total monetary value of the order in the country's minor-unit-free currency (e.g. COP). Mandatory because for CASH orders this is the exact amount the courier must collect from the client (the courier charges total_value + user_tip); for ONLINE orders it is still required for billing, insurance and reconciliation. It must be at least 1 and should reflect the full price the client pays, including any surcharges — not only the sum of product prices.

vehicle_type
required
string
Enum: "CAR" "BIKE"

Required. Vehicle used for the delivery, which determines couriers eligible for assignment and the max cargo size. Send CAR for large orders that do not fit in a standard Rappi courier bag (43 x 43 x 43 cm); otherwise send BIKE and Rappi will assign either a motorcycle or a bicycle.

payment_method
required
string
Enum: "CASH" "ONLINE"

Required. How the client pays. It changes what the courier does on delivery, so it cannot be defaulted: CASH means the courier collects total_value + user_tip from the client on arrival (the retailer must have cash collection enabled); ONLINE means the order is already paid and the courier collects nothing.

required
Array of objects (ActionPointV3DTO)

Required, at least 2. The ordered list of stops the courier makes to fulfill the order. Each action point is either a store (location_type: STORE) or the client (location_type: CLIENT), and at each one the courier either picks up or drops off products (action_type). Every order must contain at least one STORE and at least one CLIENT action point — that is why a lone stop is never valid. The array order is the route order the courier follows.

order_id
required
string [ 1 .. 255 ] characters

Required, except when duplicating an order with parent_order_id (send one or the other, never both). Your own identifier for this order. It must be unique among your active orders — the API rejects a duplicate order_id with ALREADY_EXTERNAL_ORDER_ID (a value is reusable only after its previous order was canceled). This uniqueness is also what makes retries safe: it is used as the idempotency key, so re-sending the same request will not create a second order. It is also how you correlate this order across the status webhook and other endpoints.

user_tip
number >= 0

The Tip that the client wants to pay the courier. If the order is paid in cash, the courier will charge the total_value + tip. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

partner_tip
number >= 0

The tip that the partner wants to pay the courier. This tip will not be charged to the user, it will be charged to the partner in the order charge. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

object

Client contact and address information. Required whenever the order has a CLIENT action point (essentially every delivery): its address/coordinates are used as the location of that stop, and its phone/email receive the tracking link and delivery notifications. Provide a precise address with a complement (apt/office) so the courier can find the client.

partner_channel
string
Enum: "ECOMMERCE" "MOBILE_APP" "PHONE" "INTERNAL"

Partner's channel for the order. The way the order was received. We don't do anything with this, we just store it and show it to you

priority_enabled
boolean
Default: false

Flag to enable priority delivery for this order

deliver_at
string

The date at which the order should be delivered. It should be a valid UTC date time in ISO format (e.g., 2024-05-23T23:09:49.530Z).Only add this field if you want to schedule the order. Do not use it for immediate deliveries.

parent_order_id
number

Duplicates an existing order instead of creating a new one from scratch: send the rappi_order_id of the order being duplicated here and omit order_id (exactly one of the two must be present). The duplicate gets its own identifier derived from the original, in the form {original order_id}:cargo:duplicate:{n}. Duplicating a duplicate links the new order to the original parent, so there is only ever one level of parenthood. Use order-creation-body to obtain the original body with this field already filled in.

in_store_reference_id
string

Can be a shorter or different version of the order_id, used in the store, and easier to ask for by the courier

preparation_time
number >= 1

Preparation time of an order in minutes. The assignation algorithm will use this information to time the arrival of the driver as close to the end of the preparation time as possible.

requires_photo
boolean

Indicates if the order requires a photo to be taken at the time of delivery. Overrides the retailer configuration.

requires_handshake
boolean

Indicates if the order requires a code to be handed by the user at the time of delivery. Overrides the retailer configuration.

handshake_code
string

Caller-supplied code cargo should use for this order's handshake, instead of generating one. Must be a numeric string, 3 to 6 digits long — that length rule is the same for every order, whatever flow it resolves to. Honouring the code is what depends on the flow: it is supported on the basic RESTAURANT flow (one store pick-up followed by one client drop-off, with no picking, check-in or return), while an order that resolves to RAPPI_FAVOR (multi-stop or inverse) is rejected with 400 once its flow is known, because cargo cannot register the code with the handshake service in time for that flow. Only takes effect when the order actually ends up requiring a handshake — send requires_handshake: true alongside this field. If the order does not require a handshake, this value is silently ignored. An empty (or whitespace-only) string is treated exactly like omitting the field: it is dropped, and cargo generates the code itself — callers that build the body from a form or a spreadsheet can leave the column blank instead of having to strip the key.

sales_channel
string

Sales channel from where the order was created.

use_optimal_pp_order
boolean

Indicates if the order should be rearranged to optimize the order of the action points.

slot_id
number

Slot id used to schedule the order. When provided, the order is scheduled to the slot's date and time (midpoint between start_time and end_time) and slot.current is incremented after creation.

Responses

Response Schema: application/json
cargo_order_id
required
bigint
rappi_order_id
required
bigint
external_order_id
required
string | number
tracking_url
required
string

This link allows the customer to track the order status in realtime. It will be sent via SMS and Email to the client.

eta
required
number
required
object (IntervalDto)
trip_distance
required
number

It is an estimated distance, calculated by a proprietary service in Rappi. This can be used to estimate the cost of the delivery service.

estimated_price
required
number

It is an estimated price based on your billing info.

requires_handshake
required
boolean

Indicates if the order will need handshake code to verify delivery.

rain_charge
required
boolean

Flag that indicates if the order has a rain charge.

raining_charge
required
number

It is an estimated price based on your billing info.

high_demand_charge
required
number

It is an estimated price based on your billing info.

Request samples

Content type
application/json
Example

A simple order from store to client

{
  • "total_value": 40000,
  • "user_tip": 1500,
  • "vehicle_type": "BIKE",
  • "payment_method": "ONLINE",
  • "action_points": [
    • {
      },
    • {
      }
    ],
  • "client_info": {
    • "email": "oscar@yahoo.com",
    • "phone": "3234334356",
    • "first_name": "Oscar",
    • "last_name": "Perez",
    • "address": "calle 93 #19-58",
    • "lat": 4.678646,
    • "lng": -74.05549,
    • "complement": "edificio X apartamento Y",
    • "city": "Bogota",
    • "comments": "Dejar en porteria",
    • "zip_code": "110221"
    },
  • "order_id": "lx3eRfCZ49-WTS57",
  • "in_store_reference_id": "WTS57"
}

Response samples

Content type
application/json
{
  • "cargo_order_id": 8907,
  • "rappi_order_id": 11232442,
  • "external_order_id": "ABC123XYZ, 123456",
  • "tracking_url": "https://cargo-tracking.rappi.com.co/eta/078c958514a82431bd72a2f39d9f9613",
  • "eta": 31,
  • "eta_interval": {
    • "lower": 28,
    • "upper": 35
    },
  • "trip_distance": 0,
  • "estimated_price": 0,
  • "requires_handshake": true,
  • "rain_charge": true,
  • "raining_charge": 0,
  • "high_demand_charge": 0
}

Check if an order can be created

Rappi makes some validations before allowing the creation of an order. In order to verify that the order-create endpoint will have a successful response, this endpoint can be used. This can be useful to block the creation of the order in the partners system in cases where Rappi Cargo is the only delivery provider.

Additionally, the endpoint provides extra insights regarding the order that may be useful to receive before creating the order such as the ETA and the distance of the trip. This endpoint only goes through the validations, without creating the order.

The validations that Rappi does are:

  1. All of the action points are inside a Rappi coverage area. Ask your commercial contact for a map regarding Rappi's coverage in LatAm.

  2. The travel time between the action points is under 40 minutes. This is the journey from the first to the last action point. Travel time is estimated by a proprietary service that determines the travel time between two coordinates.

  3. There is current courier availability.

If any of these fail, the endpoint will respond with an error state and the reason for the error.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
total_value
required
number >= 1

Required. Total monetary value of the order in the country's minor-unit-free currency (e.g. COP). Mandatory because for CASH orders this is the exact amount the courier must collect from the client (the courier charges total_value + user_tip); for ONLINE orders it is still required for billing, insurance and reconciliation. It must be at least 1 and should reflect the full price the client pays, including any surcharges — not only the sum of product prices.

vehicle_type
required
string
Enum: "CAR" "BIKE"

Required. Vehicle used for the delivery, which determines couriers eligible for assignment and the max cargo size. Send CAR for large orders that do not fit in a standard Rappi courier bag (43 x 43 x 43 cm); otherwise send BIKE and Rappi will assign either a motorcycle or a bicycle.

payment_method
required
string
Enum: "CASH" "ONLINE"

Required. How the client pays. It changes what the courier does on delivery, so it cannot be defaulted: CASH means the courier collects total_value + user_tip from the client on arrival (the retailer must have cash collection enabled); ONLINE means the order is already paid and the courier collects nothing.

required
Array of objects (ActionPointV3DTO)

Required, at least 2. The ordered list of stops the courier makes to fulfill the order. Each action point is either a store (location_type: STORE) or the client (location_type: CLIENT), and at each one the courier either picks up or drops off products (action_type). Every order must contain at least one STORE and at least one CLIENT action point — that is why a lone stop is never valid. The array order is the route order the courier follows.

user_tip
number >= 0

The Tip that the client wants to pay the courier. If the order is paid in cash, the courier will charge the total_value + tip. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

partner_tip
number >= 0

The tip that the partner wants to pay the courier. This tip will not be charged to the user, it will be charged to the partner in the order charge. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

object

Client contact and address information. Required whenever the order has a CLIENT action point (essentially every delivery): its address/coordinates are used as the location of that stop, and its phone/email receive the tracking link and delivery notifications. Provide a precise address with a complement (apt/office) so the courier can find the client.

partner_channel
string
Enum: "ECOMMERCE" "MOBILE_APP" "PHONE" "INTERNAL"

Partner's channel for the order. The way the order was received. We don't do anything with this, we just store it and show it to you

priority_enabled
boolean
Default: false

Flag to enable priority delivery for this order

Responses

Response Schema: application/json
service_delivery
required
string

If the field answers IMMEDIATE_DELIVERY this means Cargo is able to perform a delivery for the retailer

active
required
boolean
eta_for_immediate_delivery
required
number

It is an estimated time of arrival, calculated by a proprietary service in Rappi. This time of arrival can be used to show the user an ETA.

trip_distance
required
number

It is an estimated distance in Kilometers, calculated by a proprietary service in Rappi. This can be used to estimate the cost of the delivery service. Cargo charges using the ceiling function on the trip distance to turn it into an integer.

required
object

Time interval for the immediate delivery

internal_validations
required
object
estimated_price
required
number

It is an estimated price based on your billing info.

rain_charge
required
number

Flag that indicates if the order has a rain charge.

raining_charge
required
number

It is an estimated price based on your billing info.

high_demand_charge
required
number

It is an estimated price based on your billing info.

Request samples

Content type
application/json
Example

A simple order from store to client

{
  • "total_value": 40000,
  • "user_tip": 1500,
  • "vehicle_type": "BIKE",
  • "payment_method": "ONLINE",
  • "action_points": [
    • {
      },
    • {
      }
    ],
  • "client_info": {
    • "email": "oscar@yahoo.com",
    • "phone": "3234334356",
    • "first_name": "Oscar",
    • "last_name": "Perez",
    • "address": "calle 93 #19-58",
    • "lat": 4.678646,
    • "lng": -74.05549,
    • "complement": "edificio X apartamento Y",
    • "city": "Bogota",
    • "comments": "Dejar en porteria",
    • "zip_code": "110221"
    }
}

Response samples

Content type
application/json
{
  • "service_delivery": "IMMEDIATE_DELIVERY",
  • "active": true,
  • "eta_for_immediate_delivery": 30,
  • "trip_distance": 3.14,
  • "eta_interval_for_immediate_delivery": {
    • "lower": 28,
    • "upper": 35
    },
  • "internal_validations": { },
  • "estimated_price": 0,
  • "rain_charge": 0,
  • "raining_charge": 0,
  • "high_demand_charge": 0
}

Duplicate an order — get the body that created it

Returns the request body that created an existing order, already prepared to be sent back to order-create. It is the shortcut for duplicating an order — repeating a delivery with the same stores, client, products and options — without rebuilding the payload on your side.

Typical uses are a delivery that came back to the store and has to go out again, a client that asks for the same order later in the day, or a re-attempt after a failed delivery.

How to use it

  1. GET /v3/order-creation-body/{rappi_order_id} with the rappi_order_id Cargo returned when the original order was created.
  2. Take the body from the response and change anything you need (products, tip, deliver_at, …). Everything else can be sent as is.
  3. POST that body to order-create. The response is the usual create response, with the rappi_order_id of the new order.

What comes prepared in the body

  • order_id is removed. The duplicate does not reuse your identifier: Cargo derives one from the original, in the form {original order_id}:cargo:duplicate:{n}, where n grows with each duplicate. It is returned to you in the create response.
  • parent_order_id is set to the rappi_order_id of the original order. This is what links the duplicate to it, and it replaces order_id — send one or the other, never both.
  • Duplicating a duplicate keeps a single level of parenthood: the new order is linked to the original parent, not to the duplicate you copied from.

Things to keep in mind

  • The body is a copy of what you sent originally, not of the order's current state. Changes made to the order after creation (cancellations, status, courier) are not reflected.
  • Creating the duplicate runs the full validation flow again — coverage, travel time and courier availability are re-evaluated at that moment — so a duplicate can be rejected even though the original went through.
  • Only orders that belong to the account of the user-token are returned. Orders of another account are reported as 404, the same as orders that do not exist.
path Parameters
rappi_order_id
required
number
Example: 123456789

Rappi identifier of the order to duplicate — the rappi_order_id returned when it was created.

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
required
object

The body that created the original order, ready to be sent to order-create to duplicate it. order_id is removed and parent_order_id carries the rappi_order_id of the original order.

total_value
required
number >= 1

Required. Total monetary value of the order in the country's minor-unit-free currency (e.g. COP). Mandatory because for CASH orders this is the exact amount the courier must collect from the client (the courier charges total_value + user_tip); for ONLINE orders it is still required for billing, insurance and reconciliation. It must be at least 1 and should reflect the full price the client pays, including any surcharges — not only the sum of product prices.

vehicle_type
required
string
Enum: "CAR" "BIKE"

Required. Vehicle used for the delivery, which determines couriers eligible for assignment and the max cargo size. Send CAR for large orders that do not fit in a standard Rappi courier bag (43 x 43 x 43 cm); otherwise send BIKE and Rappi will assign either a motorcycle or a bicycle.

payment_method
required
string
Enum: "CASH" "ONLINE"

Required. How the client pays. It changes what the courier does on delivery, so it cannot be defaulted: CASH means the courier collects total_value + user_tip from the client on arrival (the retailer must have cash collection enabled); ONLINE means the order is already paid and the courier collects nothing.

required
Array of objects (ActionPointV3DTO)

Required, at least 2. The ordered list of stops the courier makes to fulfill the order. Each action point is either a store (location_type: STORE) or the client (location_type: CLIENT), and at each one the courier either picks up or drops off products (action_type). Every order must contain at least one STORE and at least one CLIENT action point — that is why a lone stop is never valid. The array order is the route order the courier follows.

order_id
required
string [ 1 .. 255 ] characters

Required, except when duplicating an order with parent_order_id (send one or the other, never both). Your own identifier for this order. It must be unique among your active orders — the API rejects a duplicate order_id with ALREADY_EXTERNAL_ORDER_ID (a value is reusable only after its previous order was canceled). This uniqueness is also what makes retries safe: it is used as the idempotency key, so re-sending the same request will not create a second order. It is also how you correlate this order across the status webhook and other endpoints.

user_tip
number >= 0

The Tip that the client wants to pay the courier. If the order is paid in cash, the courier will charge the total_value + tip. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

partner_tip
number >= 0

The tip that the partner wants to pay the courier. This tip will not be charged to the user, it will be charged to the partner in the order charge. Tip directly paid to the courier. It is recommended that orders include tip because it makes them more attractive to couriers, thus they are incentivized to accept the orders quicker. This must be a positive integer. This should not be greater than the total_value of the order

object

Client contact and address information. Required whenever the order has a CLIENT action point (essentially every delivery): its address/coordinates are used as the location of that stop, and its phone/email receive the tracking link and delivery notifications. Provide a precise address with a complement (apt/office) so the courier can find the client.

partner_channel
string
Enum: "ECOMMERCE" "MOBILE_APP" "PHONE" "INTERNAL"

Partner's channel for the order. The way the order was received. We don't do anything with this, we just store it and show it to you

priority_enabled
boolean
Default: false

Flag to enable priority delivery for this order

deliver_at
string

The date at which the order should be delivered. It should be a valid UTC date time in ISO format (e.g., 2024-05-23T23:09:49.530Z).Only add this field if you want to schedule the order. Do not use it for immediate deliveries.

parent_order_id
number

Duplicates an existing order instead of creating a new one from scratch: send the rappi_order_id of the order being duplicated here and omit order_id (exactly one of the two must be present). The duplicate gets its own identifier derived from the original, in the form {original order_id}:cargo:duplicate:{n}. Duplicating a duplicate links the new order to the original parent, so there is only ever one level of parenthood. Use order-creation-body to obtain the original body with this field already filled in.

in_store_reference_id
string

Can be a shorter or different version of the order_id, used in the store, and easier to ask for by the courier

preparation_time
number >= 1

Preparation time of an order in minutes. The assignation algorithm will use this information to time the arrival of the driver as close to the end of the preparation time as possible.

requires_photo
boolean

Indicates if the order requires a photo to be taken at the time of delivery. Overrides the retailer configuration.

requires_handshake
boolean

Indicates if the order requires a code to be handed by the user at the time of delivery. Overrides the retailer configuration.

handshake_code
string

Caller-supplied code cargo should use for this order's handshake, instead of generating one. Must be a numeric string, 3 to 6 digits long — that length rule is the same for every order, whatever flow it resolves to. Honouring the code is what depends on the flow: it is supported on the basic RESTAURANT flow (one store pick-up followed by one client drop-off, with no picking, check-in or return), while an order that resolves to RAPPI_FAVOR (multi-stop or inverse) is rejected with 400 once its flow is known, because cargo cannot register the code with the handshake service in time for that flow. Only takes effect when the order actually ends up requiring a handshake — send requires_handshake: true alongside this field. If the order does not require a handshake, this value is silently ignored. An empty (or whitespace-only) string is treated exactly like omitting the field: it is dropped, and cargo generates the code itself — callers that build the body from a form or a spreadsheet can leave the column blank instead of having to strip the key.

sales_channel
string

Sales channel from where the order was created.

use_optimal_pp_order
boolean

Indicates if the order should be rearranged to optimize the order of the action points.

slot_id
number

Slot id used to schedule the order. When provided, the order is scheduled to the slot's date and time (midpoint between start_time and end_time) and slot.current is incremented after creation.

Response samples

Content type
application/json
{
  • "body": {
    • "total_value": 20500,
    • "user_tip": 0,
    • "partner_tip": 0,
    • "vehicle_type": "BIKE",
    • "payment_method": "ONLINE",
    • "action_points": [
      ],
    • "client_info": {
      },
    • "partner_channel": "PHONE",
    • "priority_enabled": false,
    • "deliver_at": "2022-10-13T04:23:03.560Z",
    • "order_id": "123456744",
    • "parent_order_id": 123456789,
    • "in_store_reference_id": "string",
    • "preparation_time": 20,
    • "requires_photo": true,
    • "requires_handshake": true,
    • "handshake_code": "482",
    • "sales_channel": "string",
    • "use_optimal_pp_order": true,
    • "slot_id": 42
    }
}

Cancel an order

This API call gives the retailer the possibility to cancel an order in case he needs to. The order can only be canceled by the retailer when it is in state created, in_progress or in_store. Once the order is on_the_route (the courier has the products), the order cannot be canceled by the retailer.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
external_order_id
string [ 1 .. 255 ] characters

Order id in your database

rappi_order_id
number

Id of generated Rappi order

cargo_order_id
number

Order id in cargo's system

partner_cancelation_reason
string
Enum: "CANCELED_BY_END_USER" "WILL_USE_OTHER_PROVIDER" "ASSIGNMENT_TOOK_TOO_LONG" "RT_TOOK_TOO_LONG" "UNAVAILABLE_PRODUCTS" "PAYMENT_FAILED" "WRONG_ORDER_DATA" "POSSIBLE_FRAUD_RT" "POSSIBLE_FRAUD_USER" "WILL_CREATE_NEW_ORDER" "RT_DOES_NOT_ANSWER" "OTHER"

The cancelation reason for the order. While this field is not required, it helps in understanding the operative issues that may occur and to analyze the data to improve operations. The possible reasons are: CANCELED_BY_END_USER: The end user asked the partner to cancel the order. WILL_USE_OTHER_PROVIDER: The partner will use another logistics provider to deliver this order. ASSIGNMENT_TOOK_TOO_LONG: Rappi took too long to assign a driver. RT_TOOK_TOO_LONG: The assigned Rappi took too long getting to the store, or getting to the client. UNAVAILABLE_PRODUCTS: One or more products were unavailable and the order cannot be delivered this way. PAYMENT_FAILED: The online payment failed after the order was created. WRONG_ORDER_DATA: The order was created with invalid data. POSSIBLE_FRAUD_RT: The partner suspects the RT could be fraudulent. POSSIBLE_FRAUD_USER: The partner suspects the end user could be fraudulent. WILL_CREATE_NEW_ORDER: Order will be created with another data RT_DOES_NOT_ANSWER: The assigned RT does not answer the phone and is not completing the order. OTHER: Your reason is not listed here, please specify in the "partner_cancelation_reason_other" property.

partner_cancelation_reason_other
string

If you sent OTHER as the reason, specify here what reason you did not find

Responses

Response Schema: application/json
successfull
boolean

Indicates if cancellation was succesful

Request samples

Content type
application/json
{
  • "external_order_id": "123456744",
  • "rappi_order_id": 958257716,
  • "cargo_order_id": 109069,
  • "partner_cancelation_reason": "POSSIBLE_FRAUD_RT",
  • "partner_cancelation_reason_other": "I no longer wanted to deliver the product"
}

Response samples

Content type
application/json
{
  • "successfull": true
}

Get the status of an order.

This endpoint is used to get updates on the state of an order.

It can either be called by sending a POST request to /order-status or by using the order status webhook. In order to configure the webhook, contact a KAM of the Rappi Cargo team and provide us with the endpoint where the status calls will be sent and, if needed, the header that must be included. The webhook sends updates every time the status of the order changes. The status changes can be repeated, for example, an order with multiple action points will have multiple on_the_route events when moving between action points.

The list of possible order status is available here

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
external_order_id
string <= 255 characters >= 1

Order id in your database

rappi_order_id
number

Id of generated Rappi order

cargo_order_id
number

Order id in cargo's system

Responses

Response Schema: application/json
estimated_price
required
number

Value estimated for the order

estimated_tax_base_price
required
number

Value estimated for the order

in_store_reference_id
required
object

In store reference id

sales_channel
required
object

Sales channel from where the order was created.

order_ready_at
required
object

Order ready at

payment_method
required
string

Payment method used. CASH or ONLINE

rain_charge
required
object

States if a rain charge applies for this order

raining_charge
required
object

States if a rain charge applies for this order

high_demand_charge
required
number

Value estimated for the order

version
required
number

Version of the endpoint that created this order.

handoff_code
required
string

This represents the code that the store must give to the courier with the order. We generate the code some time after the creation of the order, so it might be null for some seconds. We will send a request to your sever as soon as we generate the code. The payload for such request has the same structure as the order status changes requests. Both handoff_code and handoff_qr are generated at the same time.

handoff_qr
required
string

This represents the QR code that the store must give to the courier with the order. We suggest using a library to render the actual QR from this string. We generate the qr some time after the creation of the order, so it might be null for some seconds. We will send a request to your sever as soon as we generate the QR. The payload for such request has the same structure as the order status changes requests. Both handoff_code and handoff_qr are generated at the same time.

was_processed_by_agent
required
boolean

This attribute is true if the order was closed by a support agent.

deliver_at
required
string
rappi_order_id
required
string

This represents the rappi order id

external_order_id
required
string

Represents the id on your system

callback_header
required
string
callback_header_value
required
string
cargo_order_id
required
string

Represents the id in Cargo's system

state
required
string

Represents the status of the order. The possible states are available here.

order_created_at
required
string
retailer_id
required
number
brand_id
required
string
total_value
required
number
required
object (ClientDTOV3)
required
object (PriceDTOV3)
callBack
required
string
handshake_code
required
string
order_status_id
required
number
tracking_url
required
string
collect_cash
required
number
cancelled_at
required
string
delivered_at
required
string
delivery_assigned_at
required
string
transport_media_type
required
string
required
Array of objects (OrderHistoryV3)
required
Array of objects (ActionPointDTOV3)
state_detail
required
string
was_cancelled_by_integration
required
boolean
required
Array of objects (OrderModificationDto)
eta
required
string
current_eta
required
number

Minutes until delivery

final_delivery_point_image
required
object

Final delivery point image url of the order when the courier wasn't able to deliver correctly and had to leave the order in a safe place

final_delivery_comments
required
object

Final delivery comments of the order when the courier wasn't able to deliver correctly and had to leave the order in a safe place

final_delivery_lat
required
object

Final delivery lat of the order when the courier wasn't able to deliver correctly and had to leave the order in a safe place

final_delivery_lng
required
object

Final delivery lng of the order when the courier wasn't able to deliver correctly and had to leave the order in a safe place

object

ETA with min/max delivery times and publishable range

object (StoreKeeperDTOV3)
cancelation_reason
string
Enum: "client_doesnt_answer" "sk_doesnt_answer" "lack_of_rt" "wrong_address_client_wants_to_change_orders" "problems_with_client_payment" "product_not_available" "client_fraud_suspicion" "technical_problems" "sk_doesnt_want_delivery_order_with_product" "another_sk_took_order" "closed_store" "delivery_delay" "big_order_rt_innapropiate_vehicle" "sk_couldnt_complete_order" "duplicated_order" "incomplete_order_bad_state" "does_not_work_with_rappi" "didnt_cancel_by_automation" "released_with_product" "wants_cancel_between_eta_no_delay" "price_difference" "client_whim_not_allowed_favor" "billing_error" "inner_test" "review" "cancel_by_user" "too_many_releases" "cancel_by_automation" "badly_located_pin" "client_wanted_to_change_address" "client_doesnt_receive" "technical_problems_ally" "rt_couldnt_continue_with_product" "client_doesnt_receive_problems_with_order" "client_doesnt_receive_wanted_to_change_products" "client_doesnt_receive_duplicated_order" "order_not_closed" "product_not_available_at_store" "client_doesnt_receive_bad_state" "rt_couldnt_continue" "client_doesnt_have_how_to_pay" "client_wants_to_change_payment_method" "client_doesnt_receive_wants_to_cancel" "limbo" "other" "relaunch"

The reason for the cancellation of the order

cancel_tipification
string
Enum: "EARLY" "RT_TO_STORE" "RT_IN_STORE" "RT_TO_USER" "RT_AT_USER" "DELAY_RT" "LACK_OF_RT" "LATE_ASSIGNMENT" "RT_ISSUE"

The tipification of the cancellation of the order

cancelation_moment
string
Enum: "RT_UNASSIGNED" "RT_TO_STORE" "RT_IN_STORE" "RT_TO_USER" "RT_AT_USER"

The moment of the cancellation of the order

cancellation_username
object

The name of the user that sent the cancellation request. It will be Null if the cancellation was made by Rappi.

order_ids_in_bundle
Array of numbers

The Rappi Order Ids with which this order is bundled. This means that the same driver is assigned to these orders and will deliver them in a route. This attribute will only be sent when the status changes to “in_progress” meaning that a driver has just been assigned to the order. If this order is not bundled the attribute will be an empty array.

debt_cancellation_user_name
string

The name of the user that cancelled the debt of the order

debt_cancelled_at
string

The datetime at which the debt was cancelled

Callbacks

Request samples

Content type
application/json
{
  • "external_order_id": "123456744",
  • "rappi_order_id": 958257716,
  • "cargo_order_id": 109069
}

Response samples

Content type
application/json
{
  • "eta_range": {
    • "delivery_min_time": "35",
    • "delivery_max_time": "50",
    • "delivery_time": "40",
    • "eta_publish": "2:35 PM - 2:50 PM"
    },
  • "estimated_price": 3,
  • "estimated_tax_base_price": 3,
  • "in_store_reference_id": { },
  • "sales_channel": { },
  • "order_ready_at": "2022-09-12T21:41:39.694Z",
  • "payment_method": "ONLINE",
  • "rain_charge": { },
  • "raining_charge": { },
  • "high_demand_charge": 3,
  • "version": 3,
  • "handoff_code": "3756",
  • "handoff_qr": "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",
  • "was_processed_by_agent": true,
  • "deliver_at": "2022-09-12T21:41:39.694Z",
  • "rappi_order_id": 11232442,
  • "external_order_id": "MANDNFA-234",
  • "callback_header": "ApiToken",
  • "callback_header_value": "e093b561-7922-4c40-92d1-1ab0a1dd8a51",
  • "cargo_order_id": 11232442,
  • "state": "in_progress",
  • "order_created_at": "2022-09-12T21:41:39.694Z",
  • "retailer_id": 18,
  • "brand_id": 11232442,
  • "total_value": 22000,
  • "client": {
    • "first_name": "Juan",
    • "last_name": "Perez",
    • "phone": "3001234567",
    • "address": "742 de Evergreen Terrace",
    • "lat": 4.60971,
    • "lng": -74.08175,
    • "email": "fake@email.com",
    • "address_description": "Apartamento 1229",
    • "address_comments": "Dejar en porteria"
    },
  • "storeKeeper": {
    • "id": 11232442,
    • "phone": "3001234567",
    • "first_name": "Juan",
    • "email": "test@test.com",
    • "last_name": "Perez",
    • "lat": 4.60971,
    • "lng": -74.08175,
    • "transport_media_type": "car",
    • "timestamp": "2025-01-22T13:38:20.000Z"
    },
  • "price": {
    • "total": 1000,
    • "courier_tip_total": 1000
    },
  • "callBack": "https://myserver.com/",
  • "handshake_code": "ApiToken",
  • "order_status_id": 24,
  • "tracking_url": "https://cargo-tracking.dev.rappi.com/eta/6ead8d94e5d0ic90ce8237411da31825",
  • "collect_cash": 0,
  • "cancelled_at": "2022-09-12T21:41:39.694Z",
  • "delivered_at": "2022-09-12T21:41:39.694Z",
  • "delivery_assigned_at": "2022-09-12T21:41:39.694Z",
  • "transport_media_type": "car",
  • "order_update": [
    • {
      }
    ],
  • "action_points": [
    • {
      }
    ],
  • "state_detail": "canceled_by_fraud",
  • "was_cancelled_by_integration": true,
  • "order_modification": [
    • {
      }
    ],
  • "eta": "string",
  • "cancelation_reason": "client_doesnt_answer",
  • "cancel_tipification": "EARLY",
  • "cancelation_moment": "RT_UNASSIGNED",
  • "current_eta": 27,
  • "final_delivery_point_image": "https://www.image.com/image.png",
  • "final_delivery_comments": "Señor deje su pedido en portería, recibio Juan Lopez",
  • "final_delivery_lat": 4.741345,
  • "final_delivery_lng": -74.741345,
  • "cancellation_username": "User 123",
  • "order_ids_in_bundle": [
    • 0
    ],
  • "debt_cancellation_user_name": "string",
  • "debt_cancelled_at": "string"
}

Callback payload samples

Callback
POST: Updates are sent when the orders status changes. W
Content type
application/json
{
  • "eta_range": {
    • "delivery_min_time": "35",
    • "delivery_max_time": "50",
    • "delivery_time": "40",
    • "eta_publish": "2:35 PM - 2:50 PM"
    },
  • "estimated_price": 3,
  • "estimated_tax_base_price": 3,
  • "in_store_reference_id": { },
  • "sales_channel": { },
  • "order_ready_at": "2022-09-12T21:41:39.694Z",
  • "payment_method": "ONLINE",
  • "rain_charge": { },
  • "raining_charge": { },
  • "high_demand_charge": 3,
  • "version": 3,
  • "handoff_code": "3756",
  • "handoff_qr": "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",
  • "was_processed_by_agent": true,
  • "deliver_at": "2022-09-12T21:41:39.694Z",
  • "rappi_order_id": 11232442,
  • "external_order_id": "MANDNFA-234",
  • "callback_header": "ApiToken",
  • "callback_header_value": "e093b561-7922-4c40-92d1-1ab0a1dd8a51",
  • "cargo_order_id": 11232442,
  • "state": "in_progress",
  • "order_created_at": "2022-09-12T21:41:39.694Z",
  • "retailer_id": 18,
  • "brand_id": 11232442,
  • "total_value": 22000,
  • "client": {
    • "first_name": "Juan",
    • "last_name": "Perez",
    • "phone": "3001234567",
    • "address": "742 de Evergreen Terrace",
    • "lat": 4.60971,
    • "lng": -74.08175,
    • "email": "fake@email.com",
    • "address_description": "Apartamento 1229",
    • "address_comments": "Dejar en porteria"
    },
  • "storeKeeper": {
    • "id": 11232442,
    • "phone": "3001234567",
    • "first_name": "Juan",
    • "email": "test@test.com",
    • "last_name": "Perez",
    • "lat": 4.60971,
    • "lng": -74.08175,
    • "transport_media_type": "car",
    • "timestamp": "2025-01-22T13:38:20.000Z"
    },
  • "price": {
    • "total": 1000,
    • "courier_tip_total": 1000
    },
  • "callBack": "https://myserver.com/",
  • "handshake_code": "ApiToken",
  • "order_status_id": 24,
  • "tracking_url": "https://cargo-tracking.dev.rappi.com/eta/6ead8d94e5d0ic90ce8237411da31825",
  • "collect_cash": 0,
  • "cancelled_at": "2022-09-12T21:41:39.694Z",
  • "delivered_at": "2022-09-12T21:41:39.694Z",
  • "delivery_assigned_at": "2022-09-12T21:41:39.694Z",
  • "transport_media_type": "car",
  • "order_update": [
    • {
      }
    ],
  • "action_points": [
    • {
      }
    ],
  • "state_detail": "canceled_by_fraud",
  • "was_cancelled_by_integration": true,
  • "order_modification": [
    • {
      }
    ],
  • "eta": "string",
  • "cancelation_reason": "client_doesnt_answer",
  • "cancel_tipification": "EARLY",
  • "cancelation_moment": "RT_UNASSIGNED",
  • "current_eta": 27,
  • "final_delivery_point_image": "https://www.image.com/image.png",
  • "final_delivery_comments": "Señor deje su pedido en portería, recibio Juan Lopez",
  • "final_delivery_lat": 4.741345,
  • "final_delivery_lng": -74.741345,
  • "cancellation_username": "User 123",
  • "order_ids_in_bundle": [
    • 0
    ],
  • "debt_cancellation_user_name": "string",
  • "debt_cancelled_at": "string"
}

List the orders of the owner of the token

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
Array
id
required
string
lat
required
number
lng
required
number
address
required
string
city
required
string
phone
required
string
zip_code
required
string
retailer_id
required
string
picking_point_id
required
number
order_type_id
required
number
order_status_id
required
number
delivery_type_id
required
number
dispatch_group_id
required
number
dispatch_group_priority
required
number
rappi_order_id
required
string
integration_external_id
required
number
external_order_id
required
string
total_value
required
number
destination_lat
required
number
destination_lng
required
number
destination_address
required
string
destination_city
required
string
destination_zip_code
required
string
destination_description
required
string
destination_comments
required
string
destination_email
required
string
destination_phone
required
string
destination_first_name
required
string
destination_last_name
required
string
destination_external_id
required
string
created_at
required
string
delivery_assigned_at
required
string
delivered_at
required
string
cancelled_at
required
string
collect_cash
required
number
roundtrip
required
boolean
roundtrip_comments
required
string
callback
required
string
sk_id
required
string
sk_phone
required
string
sk_email
required
string
sk_type
required
string
sk_reassigned
required
boolean
sk_first_name
required
string
sk_last_name
required
string
transport_media_type
required
string
sk_lat
required
number
sk_lng
required
number
sk_position_updated_at
required
string
required
object
placed_at
required
string
user_id
required
number
total_weight
required
number
total_volume
required
number
tracking_code
required
string
user_experience_rate
required
number
user_experience_comments
required
string
handshake_code
required
string
handshake_response
required
string
eta
required
number
calculated_tip
required
string
user_tip
required
string
default_tip
required
string
order_update
required
Array of strings

Response samples

Content type
application/json
[
  • {
    • "id": "",
    • "lat": 8907,
    • "lng": 8907,
    • "address": 8907,
    • "city": 8907,
    • "phone": 8907,
    • "zip_code": 8907,
    • "retailer_id": 8907,
    • "picking_point_id": 8907,
    • "order_type_id": 8907,
    • "order_status_id": 8907,
    • "delivery_type_id": 8907,
    • "dispatch_group_id": 8907,
    • "dispatch_group_priority": 8907,
    • "rappi_order_id": 8907,
    • "integration_external_id": 8907,
    • "external_order_id": 8907,
    • "total_value": 8907,
    • "destination_lat": 8907,
    • "destination_lng": 8907,
    • "destination_address": 8907,
    • "destination_city": 8907,
    • "destination_zip_code": 8907,
    • "destination_description": 8907,
    • "destination_comments": 8907,
    • "destination_email": 8907,
    • "destination_phone": 8907,
    • "destination_first_name": 8907,
    • "destination_last_name": 8907,
    • "destination_external_id": 8907,
    • "created_at": 8907,
    • "delivery_assigned_at": 8907,
    • "delivered_at": 8907,
    • "cancelled_at": 8907,
    • "collect_cash": 8907,
    • "roundtrip": 8907,
    • "roundtrip_comments": 8907,
    • "callback": 8907,
    • "sk_id": 8907,
    • "sk_phone": 8907,
    • "sk_email": 8907,
    • "sk_type": 8907,
    • "sk_reassigned": 8907,
    • "sk_first_name": 8907,
    • "sk_last_name": 8907,
    • "transport_media_type": 8907,
    • "sk_lat": 8907,
    • "sk_lng": 8907,
    • "sk_position_updated_at": 8907,
    • "additional_data": 8907,
    • "placed_at": 8907,
    • "user_id": 8907,
    • "total_weight": 8907,
    • "total_volume": 8907,
    • "tracking_code": 8907,
    • "user_experience_rate": 8907,
    • "user_experience_comments": 8907,
    • "handshake_code": 8907,
    • "handshake_response": 8907,
    • "eta": 8907,
    • "calculated_tip": 8907,
    • "user_tip": 8907,
    • "default_tip": 8907,
    • "order_update": [
      ]
    }
]

Set order ready

Calling this endpoint will mark this order as ready to be picked up. This means we will speed up the assignment process if there is no courier assigned. If there is, we will send a notification letting the courier know that the order is ready

path Parameters
rappi_order_id
required
number
header Parameters
user-token
required
string

Token

Responses

Response samples

Content type
application/json
Example
{
  • "message": "action_points.0.products should not be empty",
  • "type": "ValidationError",
  • "code": "FIELD_VALIDATION",
  • "status": 400,
  • "field": "action_points.0.products"
}

Confirm that an order was returned to the store

Confirms that an order that never reached the customer came back to your store successfully. This is the endpoint you call to close the return: the order moves to returned and the courier gets a push notification in the Rappi app telling them your store accepted the delivery back.

Call it when the courier is physically in front of you handing the order back, once you have checked that everything you expected is there. The confirmation is irreversible — from Rappi's side it is the receipt that your store already got the products or the cash back — so a second call on the same order fails.

Why it also settles the courier's debt

When an order carrying cash or products does not reach the customer, Rappi registers a debt against the courier for the value of the order, which would otherwise be discounted from their earnings. Confirming the return is what clears that debt: your confirmation is the proof that the courier gave the goods or the money back, so the two happen in the same call. This is why most of the errors below talk about the debt — they are the financial side of a return that cannot be confirmed yet.

When can it be called

The order must be in one of these states:

Status Condition
canceled only if the order was flagged as returnable (return_allowed)
failed_delivery —
failed_return —
return_in_store —
returned —

On top of that, the order must have a courier assigned, must not have been confirmed before, and must have a pending debt in Rappi's system.

Permissions

The user behind the user-token needs the ORDER_REMOVE_DEBT permission over the picking point of the order. Orders that belong to a different account are reported as 404, the same as orders that do not exist, so a wrong token cannot be used to probe for order ids.

Return orders

If you send the id of a return order created by Cargo, the confirmation is applied to the original order that generated the return, so you can always use the id you are tracking.

Retries

The debt is registered in a separate financial system and can take a few seconds to appear after the order fails, so a return can be valid and still not be confirmable for a moment. A 422 with code ORDER_WITH_WRONG_DEBT means the amount is not settled yet — wait and retry. A 422 with ORDER_HAS_NO_DEBT or ORDER_HAS_DEBT_ADJUSTMENT means there is nothing left to settle and the return needs no confirmation; do not retry those.

path Parameters
rappi_order_id
required
number
Example: 123456789

Rappi identifier of the order being returned — the rappi_order_id returned when the order was created.

header Parameters
user-token
required
string

Token

Responses

Response samples

Content type
application/json
{
  • "message": "Order with rappi_order_id: 123456789 is not eligible for debt cancelation",
  • "code": "ORDER_NOT_ELIGIBLE_FOR_DEBT_CANCELATION",
  • "status": 400
}

User

List permission groups (roles)

Returns the permission groups (roles) available for your account. Use the id of the desired group as the permission_group_id when creating or updating a user.

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
Array
id
required
number

Unique identifier of the permission group

brand_id
required
number

Identifier of the associated brand

picking_point_permissions
required
Array of strings
Items Enum: "PP_MANAGE" "PP_UPDATE_WITH_INCENTIVE_SETTINGS" "PP_UPDATE" "PP_CREATE" "PP_READ" "PP_DELETE" "ORDER_MANAGE" "ORDER_CREATE" "ORDER_CANCEL" "ORDER_REMOVE_DEBT" "ORDER_ADD_INCENTIVE" "ORDER_POSITION" "ORDER_VALIDATE" "ORDER_HAND_RT" "ORDER_READY"

Permissions related to picking points

retailer_permissions
required
Array of strings
Items Enum: "RETAILER_MANAGE" "RETAILER_READ" "RETAILER_UPDATE" "RETAILER_UPDATE_WITH_INCENTIVE_SETTINGS" "PP_MANAGE" "PP_UPDATE_WITH_INCENTIVE_SETTINGS" "PP_UPDATE" "PP_CREATE" "PP_READ" "PP_DELETE" "ORDER_MANAGE" "ORDER_CREATE" "ORDER_CANCEL" "ORDER_REMOVE_DEBT" "ORDER_ADD_INCENTIVE" "ORDER_POSITION" "ORDER_VALIDATE" "ORDER_HAND_RT" "ORDER_READY"

Permissions related to retailers

global_permissions
required
Array of strings
Items Enum: "MANAGE_ACCOUNT" "CREATE_USER" "UPDATE_USER" "DELETE_USER" "LIST_USERS" "USER_DETAIL" "CHANGE_PASSWORDS" "MI_TIENDA_GET_STORES" "MI_TIENDA_ACTIVATE_STORES" "PARTNER_PORTAL_GET_STORES" "PARTNER_PORTAL_ACTIVATE_STORES" "REPORTS" "CONTROL_TOWER" "HANDLE_ROLES" "MANAGE_SETTLEMENT" "DEV_PORTAL" "RETAILER_MANAGE" "RETAILER_READ" "RETAILER_UPDATE" "RETAILER_UPDATE_WITH_INCENTIVE_SETTINGS" "PP_MANAGE" "PP_UPDATE_WITH_INCENTIVE_SETTINGS" "PP_UPDATE" "PP_CREATE" "PP_READ" "PP_DELETE" "ORDER_MANAGE" "ORDER_CREATE" "ORDER_CANCEL" "ORDER_REMOVE_DEBT" "ORDER_ADD_INCENTIVE" "ORDER_POSITION" "ORDER_VALIDATE" "ORDER_HAND_RT" "ORDER_READY"

Global permissions

name
required
string

Name of the permission group

description
required
string

Description of the permission group

level
required
string
Enum: "GLOBAL" "RETAILER" "PICKING_POINT"

Level of the permission group (e.g., RETAILER)

created_at
required
string

Timestamp when the permission group was created. ISO String

updated_at
required
string

Timestamp when the permission group was last updated. ISO String

Response samples

Content type
application/json
[
  • {
    • "id": 123,
    • "brand_id": 12345,
    • "picking_point_permissions": [
      ],
    • "retailer_permissions": [
      ],
    • "global_permissions": [
      ],
    • "name": "Visualizador Global",
    • "description": "Ve todas las órdenes de todas las tiendas",
    • "level": "GLOBAL",
    • "created_at": "2025-01-23T16:08:30.672Z",
    • "updated_at": "2025-01-23T16:08:30.672Z"
    }
]

Creates a user in the platform

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
user_enabled
required
boolean

Whether the user can log in and use the platform right away. Send true to activate the user on creation, false to create it disabled.

email
required
string [ 5 .. 255 ] characters

Email of the user being created. Used as the login identifier, so it must be unique — creating a user with an email that already exists is rejected.

password
required
string [ 8 .. 80 ] characters

Password for the new user. Must be 8-80 characters and include at least one lowercase letter, one uppercase letter and one digit.

name
required
string [ 2 .. 60 ] characters

Full name of the user, shown across the platform.

phone
required
string [ 7 .. 15 ] characters

Phone of the user. Digits only (no spaces, dashes or country-code prefix).

confirm_password
required
string [ 8 .. 80 ] characters

Must exactly match password. The request is rejected if the two differ.

permission_group_id
required
number

Id of the permission group (role) assigned to the user. This determines what the user can do in the platform. Retrieve the available permission groups from the permission-group list endpoint or the Cargo portal.

picking_points
Array of numbers

Cargo ids of the picking points (stores) this user will have access to. Omit to grant access to all of the retailer's picking points. Use external_picking_points instead if you prefer to reference stores by your own external id.

retailers
Array of numbers

Ids of the retailers the user belongs to. Optional; when provided it must contain at least one id. Most integrations only need one retailer and can omit this.

external_picking_points
Array of strings

Picking points the user will have access to, referenced by your own external id instead of Cargo's picking_points id. Optional; when provided it must contain at least one id.

Responses

Response Schema: application/json
name
required
string

Name of the user.

email
required
string

Email of the user, used to log in.

user_enabled
required
boolean

Whether the user is currently enabled to use the platform.

id
required
number

Cargo id of the user.

has_token
required
boolean

Whether this user has an API token issued (i.e. can authenticate against this API via the user-token header).

phone
string

Phone of the user. Null if none was set.

Request samples

Content type
application/json
{
  • "user_enabled": true,
  • "email": "julian@email.com",
  • "password": "Passw0rd?",
  • "name": "Julian",
  • "phone": "3011234567",
  • "confirm_password": "Passw0rd?",
  • "picking_points": [
    • 2,
    • 1,
    • 3
    ],
  • "permission_group_id": 42,
  • "retailers": [
    • 100
    ],
  • "external_picking_points": [
    • "FH0197",
    • "FH0198"
    ]
}

Response samples

Content type
application/json
{
  • "name": "Juan",
  • "email": "juan@gmail.com",
  • "phone": "3111234567",
  • "user_enabled": false,
  • "id": 1234567,
  • "has_token": false
}

Updates a user in the platform

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
id
required
number

User id

user_enabled
boolean

Whether the user can log in and use the platform right away. Send true to activate the user on creation, false to create it disabled.

password
string [ 8 .. 80 ] characters

Password for the new user. Must be 8-80 characters and include at least one lowercase letter, one uppercase letter and one digit.

name
string [ 2 .. 60 ] characters

Full name of the user, shown across the platform.

phone
string [ 7 .. 15 ] characters

Phone of the user. Digits only (no spaces, dashes or country-code prefix).

confirm_password
string [ 8 .. 80 ] characters

Must exactly match password. The request is rejected if the two differ.

picking_points
Array of numbers

Cargo ids of the picking points (stores) this user will have access to. Omit to grant access to all of the retailer's picking points. Use external_picking_points instead if you prefer to reference stores by your own external id.

permission_group_id
number

Id of the permission group (role) assigned to the user. This determines what the user can do in the platform. Retrieve the available permission groups from the permission-group list endpoint or the Cargo portal.

retailers
Array of numbers

Ids of the retailers the user belongs to. Optional; when provided it must contain at least one id. Most integrations only need one retailer and can omit this.

external_picking_points
Array of strings

Picking points the user will have access to, referenced by your own external id instead of Cargo's picking_points id. Optional; when provided it must contain at least one id.

email
string

User email

Responses

Response Schema: application/json
name
required
string

Name of the user.

email
required
string

Email of the user, used to log in.

user_enabled
required
boolean

Whether the user is currently enabled to use the platform.

id
required
number

Cargo id of the user.

has_token
required
boolean

Whether this user has an API token issued (i.e. can authenticate against this API via the user-token header).

phone
string

Phone of the user. Null if none was set.

Request samples

Content type
application/json
{
  • "user_enabled": true,
  • "password": "Passw0rd?",
  • "name": "Julian",
  • "phone": "3011234567",
  • "confirm_password": "Passw0rd?",
  • "picking_points": [
    • 2,
    • 1,
    • 3
    ],
  • "permission_group_id": 42,
  • "retailers": [
    • 100
    ],
  • "external_picking_points": [
    • "FH0197",
    • "FH0198"
    ],
  • "id": 1234567,
  • "email": "juan@email.com"
}

Response samples

Content type
application/json
{
  • "name": "Juan",
  • "email": "juan@gmail.com",
  • "phone": "3111234567",
  • "user_enabled": false,
  • "id": 1234567,
  • "has_token": false
}

Deletes a user in the platform

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
id
required
number

Id of the user you want to delete

Responses

Response Schema: application/json
id
required
number

Cargo id of the user that was deleted.

success
required
boolean

Whether the deletion succeeded.

Request samples

Content type
application/json
{
  • "id": 1234567
}

Response samples

Content type
application/json
{
  • "id": 1234567,
  • "success": true
}

Retrieve the list of users from a retailer

query Parameters
offset
number
Example: offset=0

Number of users to skip before collecting the page. Defaults to 0 when omitted.

limit
number
Example: limit=50

Number of users to retrieve (page size). Defaults to 50 when omitted.

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
Array
name
required
string

Name of the user.

email
required
string

Email of the user, used to log in.

user_enabled
required
boolean

Whether the user is currently enabled to use the platform.

id
required
number

Cargo id of the user.

has_token
required
boolean

Whether this user has an API token issued (i.e. can authenticate against this API via the user-token header).

phone
string

Phone of the user. Null if none was set.

Response samples

Content type
application/json
[
  • {
    • "name": "Juan",
    • "email": "juan@gmail.com",
    • "phone": "3111234567",
    • "user_enabled": false,
    • "id": 1234567,
    • "has_token": false
    }
]

Retrieve the user with the id provided

path Parameters
id
required
number
Example: 1234567

Id of the user you want to retrieve

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
name
required
string

Name of the user.

email
required
string

Email of the user, used to log in.

user_enabled
required
boolean

Whether the user is currently enabled to use the platform.

id
required
number

Cargo id of the user.

has_token
required
boolean

Whether this user has an API token issued (i.e. can authenticate against this API via the user-token header).

phone
string

Phone of the user. Null if none was set.

Response samples

Content type
application/json
{
  • "name": "Juan",
  • "email": "juan@gmail.com",
  • "phone": "3111234567",
  • "user_enabled": false,
  • "id": 1234567,
  • "has_token": false
}

Picking point

Create PickingPoint.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
lat
required
number

Latitude number of the picking point

lng
required
number

Longitude number of the picking point

address
required
string

Address of the picking point

city
required
string

City of the picking point

phone
required
string

Phone number of the picking point

name
required
string

Name of the picking point

contact_name
required
string

Name of the contact in the picking point

contact_email
required
string

Email of the contact in the picking point

preparation_time
required
number

Preparation time of an order in minutes. The assignation algorithm will use this information to time the arrival of the driver as close to the end of the preparation time as possible.

zip_code
string

Zip code of the picking point

status
number
Default: 1

Status of the picking point

external_id
string

ID in your database, of the picking point registered in the Retailer Portal

rappi_store_id
object

The Rappi Store id of the picking point, having this value will allow us to provide an improved experience such as having the same checkin code for Rappi and Cargo orders.

default_tip
float

This sets the default tip of the picking point that takes into account semaphore limits and will be used as a tip where this picking point is the first store in an order

handshake_enabled
boolean

If the value of the order has this value or higher, a verification code will be required on delivery

return_enabled
boolean

This enables the return feature to the picking point

handoff_enabled
boolean

This enables the handoff feature, you may ask your commercial about this feature

multiple_stops_tips
float

Tip amount added to orders with multiple stops (more than 2 action points) when the retailer has multiple_stops_tips_status enabled

Responses

Response Schema: application/json
address
required
string

Address of the picking point

city
required
string

City of the picking point

contact_name
required
string

Name of the contact in the picking point

contact_email
required
object

Email of the contact in the picking point

external_id
required
number

ID in your database, of the picking point registered in the Retailer Portal

lat
required
number

Latitude number of the picking point

lng
required
number

Longitude number of the picking point

name
required
string

Name of the picking point

other
required
string

Extra information of the picking point

phone
required
string

Phone number of the picking point

preparation_time
required
number

Preparation time of an order in minutes

retailer_id
required
string

Retailer id in Cargo's DB

rappi_city_code
number

City id in Rappi's DB

rappi_store_id
number

store id in Rappi's DB

rappi_zone_id
number

Geolocation zone id in Rappi's DB

status
number

Store status

zip_code
string

Zip code of the picking point

checkin_enabled
boolean

Checkin enabled feature

return_enabled
boolean

Return enabled feature

product_return_instructions
string

Return instructions for that picking point

default_tip
float

default tip of the picking point

min_saturation_for_default_tips
float

Minimum fleet saturation (orders per courier in the zone) from which default_tip applies. Null inherits the retailer value.

Request samples

Content type
application/json
{
  • "lat": 4.60971,
  • "lng": -74.08175,
  • "address": "Carrera 123 #12 - 1",
  • "city": "Bogotá",
  • "phone": "31212345567",
  • "zip_code": "123321",
  • "status": 1,
  • "name": "Restaurante laureles",
  • "contact_name": "Julian",
  • "contact_email": "julian@email.com",
  • "preparation_time": 30,
  • "external_id": "1234567",
  • "rappi_store_id": 99019292,
  • "default_tip": 500,
  • "handshake_enabled": true,
  • "return_enabled": true,
  • "handoff_enabled": true,
  • "multiple_stops_tips": 500
}

Response samples

Content type
application/json
{
  • "address": "Calle 123 #12 1",
  • "city": "Bogotá",
  • "contact_name": "Julian",
  • "contact_email": "julian@email.com",
  • "external_id": 1234567,
  • "lat": 4.60971,
  • "lng": -74.08175,
  • "name": "Restaurant at laureles",
  • "other": "Store with 3 yellow doors",
  • "phone": "31212345567",
  • "preparation_time": 30,
  • "rappi_city_code": 1234567,
  • "rappi_store_id": 1234567,
  • "rappi_zone_id": 1234567,
  • "retailer_id": 1234567,
  • "status": 1,
  • "zip_code": "123321",
  • "checkin_enabled": true,
  • "return_enabled": true,
  • "product_return_instructions": "By the red door",
  • "default_tip": 1234,
  • "min_saturation_for_default_tips": 1.7
}

Update PickingPoint.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
id
required
number

Id of the picking point you want to update

lat
number

Latitude number of the picking point

lng
number

Longitude number of the picking point

address
string

Address of the picking point

city
string

City of the picking point

phone
string

Phone number of the picking point

zip_code
string

Zip code of the picking point

status
number
Default: 1

Status of the picking point

name
string

Name of the picking point

contact_name
string

Name of the contact in the picking point

contact_email
string

Email of the contact in the picking point

preparation_time
number

Preparation time of an order in minutes. The assignation algorithm will use this information to time the arrival of the driver as close to the end of the preparation time as possible.

external_id
string

ID in your database, of the picking point registered in the Retailer Portal

rappi_store_id
object

The Rappi Store id of the picking point, having this value will allow us to provide an improved experience such as having the same checkin code for Rappi and Cargo orders.

default_tip
float

This sets the default tip of the picking point that takes into account semaphore limits and will be used as a tip where this picking point is the first store in an order

handshake_enabled
boolean

If the value of the order has this value or higher, a verification code will be required on delivery

return_enabled
boolean

This enables the return feature to the picking point

handoff_enabled
boolean

This enables the handoff feature, you may ask your commercial about this feature

multiple_stops_tips
float

Tip amount added to orders with multiple stops (more than 2 action points) when the retailer has multiple_stops_tips_status enabled

Responses

Response Schema: application/json
address
required
string

Address of the picking point

city
required
string

City of the picking point

contact_name
required
string

Name of the contact in the picking point

contact_email
required
object

Email of the contact in the picking point

external_id
required
number

ID in your database, of the picking point registered in the Retailer Portal

lat
required
number

Latitude number of the picking point

lng
required
number

Longitude number of the picking point

name
required
string

Name of the picking point

other
required
string

Extra information of the picking point

phone
required
string

Phone number of the picking point

preparation_time
required
number

Preparation time of an order in minutes

retailer_id
required
string

Retailer id in Cargo's DB

rappi_city_code
number

City id in Rappi's DB

rappi_store_id
number

store id in Rappi's DB

rappi_zone_id
number

Geolocation zone id in Rappi's DB

status
number

Store status

zip_code
string

Zip code of the picking point

checkin_enabled
boolean

Checkin enabled feature

return_enabled
boolean

Return enabled feature

product_return_instructions
string

Return instructions for that picking point

default_tip
float

default tip of the picking point

min_saturation_for_default_tips
float

Minimum fleet saturation (orders per courier in the zone) from which default_tip applies. Null inherits the retailer value.

Request samples

Content type
application/json
{
  • "lat": 4.60971,
  • "lng": -74.08175,
  • "address": "Carrera 123 #12 - 1",
  • "city": "Bogotá",
  • "phone": "31212345567",
  • "zip_code": "123321",
  • "status": 1,
  • "name": "Restaurante laureles",
  • "contact_name": "Julian",
  • "contact_email": "julian@email.com",
  • "preparation_time": 30,
  • "external_id": "1234567",
  • "rappi_store_id": 99019292,
  • "default_tip": 500,
  • "handshake_enabled": true,
  • "return_enabled": true,
  • "handoff_enabled": true,
  • "multiple_stops_tips": 500,
  • "id": 1234567
}

Response samples

Content type
application/json
{
  • "address": "Calle 123 #12 1",
  • "city": "Bogotá",
  • "contact_name": "Julian",
  • "contact_email": "julian@email.com",
  • "external_id": 1234567,
  • "lat": 4.60971,
  • "lng": -74.08175,
  • "name": "Restaurant at laureles",
  • "other": "Store with 3 yellow doors",
  • "phone": "31212345567",
  • "preparation_time": 30,
  • "rappi_city_code": 1234567,
  • "rappi_store_id": 1234567,
  • "rappi_zone_id": 1234567,
  • "retailer_id": 1234567,
  • "status": 1,
  • "zip_code": "123321",
  • "checkin_enabled": true,
  • "return_enabled": true,
  • "product_return_instructions": "By the red door",
  • "default_tip": 1234,
  • "min_saturation_for_default_tips": 1.7
}

Delete the picking point passed by parameter.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
id
required
number

Id of the picking point you want to delete

Responses

Request samples

Content type
application/json
{
  • "id": 123445
}

Retrieve the list of the picking point of the retailer

query Parameters
offset
required
number
Example: offset=1

Amount of picking points you will skip in the a query

limit
required
number
Example: limit=50

Amount of picking points you will retrieve (amount of user per page)

orderdir
string
Example: orderdir=asc

Direction for orderby: asc or desc. Defaults to asc

orderby
string
Example: orderby=name

The attribute that the picking points will be ordered by. Note that adding this parameter will slow down the query

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
Array
address
required
string

Address of the picking point

city
required
string

City of the picking point

contact_name
required
string

Name of the contact in the picking point

contact_email
required
object

Email of the contact in the picking point

external_id
required
number

ID in your database, of the picking point registered in the Retailer Portal

lat
required
number

Latitude number of the picking point

lng
required
number

Longitude number of the picking point

name
required
string

Name of the picking point

other
required
string

Extra information of the picking point

phone
required
string

Phone number of the picking point

preparation_time
required
number

Preparation time of an order in minutes

retailer_id
required
string

Retailer id in Cargo's DB

rappi_city_code
number

City id in Rappi's DB

rappi_store_id
number

store id in Rappi's DB

rappi_zone_id
number

Geolocation zone id in Rappi's DB

status
number

Store status

zip_code
string

Zip code of the picking point

checkin_enabled
boolean

Checkin enabled feature

return_enabled
boolean

Return enabled feature

product_return_instructions
string

Return instructions for that picking point

default_tip
float

default tip of the picking point

min_saturation_for_default_tips
float

Minimum fleet saturation (orders per courier in the zone) from which default_tip applies. Null inherits the retailer value.

Response samples

Content type
application/json
[
  • {
    • "address": "Calle 123 #12 1",
    • "city": "Bogotá",
    • "contact_name": "Julian",
    • "contact_email": "julian@email.com",
    • "external_id": 1234567,
    • "lat": 4.60971,
    • "lng": -74.08175,
    • "name": "Restaurant at laureles",
    • "other": "Store with 3 yellow doors",
    • "phone": "31212345567",
    • "preparation_time": 30,
    • "rappi_city_code": 1234567,
    • "rappi_store_id": 1234567,
    • "rappi_zone_id": 1234567,
    • "retailer_id": 1234567,
    • "status": 1,
    • "zip_code": "123321",
    • "checkin_enabled": true,
    • "return_enabled": true,
    • "product_return_instructions": "By the red door",
    • "default_tip": 1234,
    • "min_saturation_for_default_tips": 1.7
    }
]

Retrieve the 5 nearest picking points to a given lat/lng

query Parameters
lat
required
number
Example: lat=4.60971

Latitude of the reference point

lng
required
number
Example: lng=-74.08175

Longitude of the reference point

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
required
Array of objects (PickingPointNearbyItemResDTO)

List of the 5 nearest picking points

Array
id
required
number

Picking point ID

name
required
string

Name of the picking point

address
required
string

Address of the picking point

city
required
string

City of the picking point

phone
required
string

Phone number of the picking point

lat
required
number

Latitude of the picking point

lng
required
number

Longitude of the picking point

retailer_id
required
number

Retailer ID

status
required
number

Status of the picking point

preparation_time
required
number

Preparation time in minutes

distance_meters
required
number

Distance in meters from the reference point

Response samples

Content type
application/json
{
  • "picking_points": [
    • {
      }
    ]
}

Get a PickingPoint.

path Parameters
id
required
number
Example: 123445

Id of the picking point you want to retrieve

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
address
required
string

Address of the picking point

city
required
string

City of the picking point

contact_name
required
string

Name of the contact in the picking point

contact_email
required
object

Email of the contact in the picking point

external_id
required
number

ID in your database, of the picking point registered in the Retailer Portal

lat
required
number

Latitude number of the picking point

lng
required
number

Longitude number of the picking point

name
required
string

Name of the picking point

other
required
string

Extra information of the picking point

phone
required
string

Phone number of the picking point

preparation_time
required
number

Preparation time of an order in minutes

retailer_id
required
string

Retailer id in Cargo's DB

rappi_city_code
number

City id in Rappi's DB

rappi_store_id
number

store id in Rappi's DB

rappi_zone_id
number

Geolocation zone id in Rappi's DB

status
number

Store status

zip_code
string

Zip code of the picking point

checkin_enabled
boolean

Checkin enabled feature

return_enabled
boolean

Return enabled feature

product_return_instructions
string

Return instructions for that picking point

default_tip
float

default tip of the picking point

min_saturation_for_default_tips
float

Minimum fleet saturation (orders per courier in the zone) from which default_tip applies. Null inherits the retailer value.

Response samples

Content type
application/json
{
  • "address": "Calle 123 #12 1",
  • "city": "Bogotá",
  • "contact_name": "Julian",
  • "contact_email": "julian@email.com",
  • "external_id": 1234567,
  • "lat": 4.60971,
  • "lng": -74.08175,
  • "name": "Restaurant at laureles",
  • "other": "Store with 3 yellow doors",
  • "phone": "31212345567",
  • "preparation_time": 30,
  • "rappi_city_code": 1234567,
  • "rappi_store_id": 1234567,
  • "rappi_zone_id": 1234567,
  • "retailer_id": 1234567,
  • "status": 1,
  • "zip_code": "123321",
  • "checkin_enabled": true,
  • "return_enabled": true,
  • "product_return_instructions": "By the red door",
  • "default_tip": 1234,
  • "min_saturation_for_default_tips": 1.7
}

Get a Checkin Code for a given PickingPoint.

query Parameters
p
required
string
Example: p=123445

Id of the picking point you want the checkin code for

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
required
object

Checkin code information

name
required
string

Picking point's name

Response samples

Content type
application/json
{
  • "checkin": {
    • "code": "8202",
    • "store_id": 123
    },
  • "name": "Restaurant laureles"
}

Fetch all the checkin codes from the picking points

header Parameters
user-token
required
string

Token

Responses

Response Schema: application/json
Array
id
required
number

Picking point ID

name
required
string

Picking point's name

checkin_code
required
string

Picking point's current checkin code

checkin_code_url
required
string

The url where at any point the checkin of that picking point can be found

external_id
string

Picking point id in your database

Response samples

Content type
application/json
[]

Refresh the Checkin Code for a given PickingPoint.

header Parameters
user-token
required
string

Token

Request Body schema: application/json
required
object (PickingPointCheckinQuery)

Responses

Response Schema: application/json
required
object

Checkin code information

name
required
string

Picking point's name

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "checkin": {
    • "code": "8202",
    • "store_id": 123
    },
  • "name": "Restaurant laureles"
}