Orders API — create and manage delivery orders

The Orders API manages the lifecycle of delivery orders from creation through final delivery or cancellation. Orders progress through a strict state machine; some transitions are triggered automatically by the Assignments API. Payments and invoices are attached to an order via sub-resource endpoints documented at the bottom of this page.

Order state machine

An order always starts in Pendiente. From there it advances as drivers are assigned and start their routes, and can be cancelled at any point except when already cancelled.

Pendiente ──(assignment created)──► En Proceso
En Proceso ──(assignment started)──► En Tránsito
En Tránsito ──(assignment finished)──► Entregado

any state ──(DELETE /ordenes/{id})──► Cancelado

State	Description
`Pendiente`	Order created, awaiting driver assignment.
`En Proceso`	Driver assigned; not yet en route.
`En Tránsito`	Driver has started the delivery.
`Entregado`	Delivery confirmed complete.
`Cancelado`	Order cancelled; terminal state.

List orders

GET /api/ordenes

string

Returns a paginated list of orders, newest first. Filter by client or status using query parameters. Required permission: ordenes:read

Query parameters

skip

integer

default:"0"

Number of records to skip for pagination.

limit

integer

default:"50"

Maximum number of records to return. Hard cap: 200.

cliente_id

integer

Return only orders belonging to this client.

estado

string

Filter by order state. One of Pendiente, En Proceso, En Tránsito, Entregado, Cancelado.

Response `200`

Array of order objects.

integer

required

Unique order identifier.

cliente_id

integer

required

ID of the client who placed the order.

estado

string

required

Current order state.

direccion_origen

string

required

Pick-up street address.

distrito_origen

string

Pick-up district.

direccion_destino

string

required

Delivery street address.

distrito_destino

string

Delivery district.

total

number

Order total amount (decimal).

fecha_creacion

string (datetime)

ISO 8601 creation timestamp.

curl "https://api.rappi2.com/api/ordenes?cliente_id=42&estado=Pendiente" \
  -H "Authorization: Bearer <token>"

Create an order

POST /api/ordenes

string

Creates a new order with initial state Pendiente. The referenced client must be active. Required permission: ordenes:write

Request body

cliente_id

integer

required

ID of an active client placing the order.

direccion_origen

string

required

Pick-up street address.

distrito_origen

string

Pick-up district.

direccion_destino

string

required

Delivery street address.

distrito_destino

string

Delivery district.

total

number

Order total amount.

Response `201`

The newly created order object.

curl -X POST https://api.rappi2.com/api/ordenes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 42,
    "direccion_origen": "Av. Javier Prado 500",
    "distrito_origen": "San Isidro",
    "direccion_destino": "Calle Las Flores 200",
    "distrito_destino": "Surco",
    "total": 35.50
  }'

Get an order

GET /api/ordenes/{orden_id}

string

Returns a single order by ID. Returns 404 if not found. Required permission: ordenes:read

Path parameters

orden_id

integer

required

Order ID.

Response `200`

Order object.

curl https://api.rappi2.com/api/ordenes/101 \
  -H "Authorization: Bearer <token>"

Update an order

PATCH /api/ordenes/{orden_id}

string

Partially updates an order. You can update addresses, total, or manually advance the estado. Note that normal state transitions are handled automatically by the Assignments API; direct state writes via this endpoint bypass those guard-rails. Required permission: ordenes:write

Path parameters

orden_id

integer

required

Order ID.

Request body

All fields are optional.

estado

string

New state. One of Pendiente, En Proceso, En Tránsito, Entregado, Cancelado.

direccion_origen

string

New pick-up address.

distrito_origen

string

New pick-up district.

direccion_destino

string

New delivery address.

distrito_destino

string

New delivery district.

total

number

Updated order total.

Response `200`

Updated order object.

curl -X PATCH https://api.rappi2.com/api/ordenes/101 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"total": 40.00}'

Cancel an order

DELETE /api/ordenes/{orden_id}

string

Sets the order state to Cancelado. Returns 400 if the order is already cancelled. This is a soft operation — the order record is preserved. Required permission: ordenes:delete

Path parameters

orden_id

integer

required

Order ID.

Response `204`

No body.

curl -X DELETE https://api.rappi2.com/api/ordenes/101 \
  -H "Authorization: Bearer <token>"

Payments

Payments are linked to a specific order and track money transfers.

List all payments

GET /api/pagos

string

Returns a global list of payments across all orders, newest first. Filter by status or date range. Required permission: pagos:read

skip

integer

default:"0"

Pagination offset.

limit

integer

default:"50"

Max records (cap 200).

estado

string

Filter by payment state: Pendiente, Pagado, Fallido, or Reembolsado.

desde

string (datetime)

Only payments on or after this ISO 8601 timestamp.

hasta

string (datetime)

Only payments on or before this ISO 8601 timestamp.

curl "https://api.rappi2.com/api/pagos?estado=Pendiente" \
  -H "Authorization: Bearer <token>"

Create a payment for an order

POST /api/ordenes/{orden_id}/pagos

string

Required permission: pagos:write

orden_id

integer

required

Order ID.

monto

number

required

Payment amount.

estado

string

default:"Pendiente"

Initial state: Pendiente, Pagado, Fallido, or Reembolsado.

referencia_banco

string

Bank reference or transaction ID.

Response 201: created payment object.

integer

required

Payment ID.

orden_id

integer

required

Parent order ID.

monto

number

required

Amount paid.

estado

string

required

Payment state.

referencia_banco

string

Bank reference.

fecha_pago

string (datetime)

Timestamp of payment record creation.

curl -X POST https://api.rappi2.com/api/ordenes/101/pagos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"monto": 35.50, "estado": "Pagado", "referencia_banco": "TXN-9981"}'

List payments for an order

GET /api/ordenes/{orden_id}/pagos

string

Required permission: pagos:read

orden_id

integer

required

Order ID.

Returns an array of payment objects for this order.

curl https://api.rappi2.com/api/ordenes/101/pagos \
  -H "Authorization: Bearer <token>"

Get a payment

GET /api/pagos/{pago_id}

string

Required permission: pagos:read

pago_id

integer

required

Payment ID.

curl https://api.rappi2.com/api/pagos/55 \
  -H "Authorization: Bearer <token>"

Update a payment

PATCH /api/pagos/{pago_id}

string

Required permission: pagos:write

pago_id

integer

required

Payment ID.

estado

string

New state.

referencia_banco

string

Updated bank reference.

curl -X PATCH https://api.rappi2.com/api/pagos/55 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"estado": "Reembolsado"}'

Delete a payment

DELETE /api/pagos/{pago_id}

string

Permanently removes the payment record. Required permission: pagos:delete

pago_id

integer

required

Payment ID.

Response 204: no body.

curl -X DELETE https://api.rappi2.com/api/pagos/55 \
  -H "Authorization: Bearer <token>"

Invoices

Invoices (facturas) are generated for orders and can reference a RUC (tax ID).

List all invoices

GET /api/facturas

string

Returns a global list of invoices, newest first. Required permission: facturas:read

skip

integer

default:"0"

Pagination offset.

limit

integer

default:"50"

Max records (cap 200).

ruc

string

Filter by tax ID (RUC).

desde

string (datetime)

Only invoices on or after this timestamp.

hasta

string (datetime)

Only invoices on or before this timestamp.

curl "https://api.rappi2.com/api/facturas?ruc=20501234567" \
  -H "Authorization: Bearer <token>"

Create an invoice for an order

POST /api/ordenes/{orden_id}/facturas

string

Required permission: facturas:write

orden_id

integer

required

Order ID.

monto

number

required

Invoice amount.

ruc

string

RUC (tax ID) of the billing entity.

url

string

URL to the PDF or external invoice document.

Response 201: created invoice object.

integer

required

Invoice ID.

orden_id

integer

required

Parent order ID.

monto

number

required

Invoice amount.

ruc

string

Tax ID.

url

string

Document URL.

fecha

string (datetime)

Invoice creation timestamp.

curl -X POST https://api.rappi2.com/api/ordenes/101/facturas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"monto": 35.50, "ruc": "20501234567", "url": "https://storage.example.com/f001.pdf"}'

List invoices for an order

GET /api/ordenes/{orden_id}/facturas

string

Required permission: facturas:read

orden_id

integer

required

Order ID.

curl https://api.rappi2.com/api/ordenes/101/facturas \
  -H "Authorization: Bearer <token>"

Get an invoice

GET /api/facturas/{factura_id}

string

Required permission: facturas:read

factura_id

integer

required

Invoice ID.

curl https://api.rappi2.com/api/facturas/12 \
  -H "Authorization: Bearer <token>"

Update an invoice

PATCH /api/facturas/{factura_id}

string

Required permission: facturas:write

factura_id

integer

required

Invoice ID.

ruc

string

New RUC.

monto

number

Updated amount.

url

string

Updated document URL.

curl -X PATCH https://api.rappi2.com/api/facturas/12 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://storage.example.com/f001-v2.pdf"}'

Delete an invoice

DELETE /api/facturas/{factura_id}

string

Permanently removes the invoice. Required permission: facturas:delete

factura_id

integer

required

Invoice ID.

Response 204: no body.

curl -X DELETE https://api.rappi2.com/api/facturas/12 \
  -H "Authorization: Bearer <token>"

Auth & Users

Operations

Logistics

Analytics

Orders API — create and manage delivery orders

Order state machine

List orders

Query parameters

Response `200`

Create an order

Request body

Response `201`

Get an order

Path parameters

Response `200`

Update an order

Path parameters

Request body

Response `200`

Cancel an order

Path parameters

Response `204`

Payments

List all payments

Create a payment for an order

List payments for an order

Get a payment

Update a payment

Delete a payment

Invoices

List all invoices

Create an invoice for an order

List invoices for an order

Get an invoice

Update an invoice

Delete an invoice

Build docs developers (and LLMs) love

Auth & Users

Operations

Logistics

Analytics

Documentation Index

​Order state machine

​List orders

​Query parameters

​Response 200

​Create an order

​Request body

​Response 201

​Get an order

​Path parameters

​Response 200

​Update an order

​Path parameters

​Request body

​Response 200

​Cancel an order

​Path parameters

​Response 204

​Payments

​List all payments

​Create a payment for an order

​List payments for an order

​Get a payment

​Update a payment

​Delete a payment

​Invoices

​List all invoices

​Create an invoice for an order

​List invoices for an order

​Get an invoice

​Update an invoice

​Delete an invoice

Build docs developers (and LLMs) love

Order state machine

List orders

Query parameters

Response `200`

Create an order

Request body

Response `201`

Get an order

Path parameters

Response `200`

Update an order

Path parameters

Request body

Response `200`

Cancel an order

Path parameters

Response `204`

Payments

List all payments

Create a payment for an order

List payments for an order

Get a payment

Update a payment

Delete a payment

Invoices

List all invoices

Create an invoice for an order

List invoices for an order

Get an invoice

Update an invoice

Delete an invoice