Orders API

Overview

The Orders API allows you to retrieve, update, and manage customer orders. Orders are automatically created after successful payment through the Checkout API.

Order Object

The Order object contains complete information about a customer’s purchase.

string

Unique identifier for the order (MongoDB ObjectId)

orderNumber

string

Human-readable order number (format: YYYY-MM-XXXX, e.g., “2024-03-0001”)

user

string

User ID who placed the order (MongoDB ObjectId)

products

array

Array of purchased products

Show product item structure

product

string

Product ID reference

quantity

integer

Quantity purchased (1-100)

price

integer

Price at time of purchase (in cents)

name

string

Product name at time of purchase

image

string

Product image URL

totals

object

Order financial totals

Show properties

subtotal

integer

Subtotal before tax and shipping (in cents)

tax

integer

Tax amount (19% IVA in Colombia)

taxRate

number

Tax rate applied (default: 0.19)

shipping

integer

Shipping cost

discount

integer

Discount amount applied

total

integer

Final total amount

status

string

Current order status

Show possible values

pending - Order created, awaiting confirmation
confirmed - Payment confirmed, preparing order
processing - Order being prepared for shipment
shipped - Order shipped, in transit
delivered - Order successfully delivered
cancelled - Order cancelled
returned - Order returned by customer

paymentStatus

string

Payment status

Show possible values

pending - Awaiting payment
processing - Payment being processed
paid - Payment successful
failed - Payment failed
refunded - Full refund issued
partially_refunded - Partial refund issued

paymentMethod

string

Payment method used: credit_card, debit_card, pse, cash_on_delivery, or bank_transfer

paymentReference

string

Stripe payment intent or transaction ID

shippingAddress

object

Delivery address

Show properties

firstName

string

First name

lastName

string

Last name

street

string

Street address

city

string

City

state

string

State/Department

zipCode

string

Postal code

country

string

Country (default: Colombia)

phone

string

Contact phone number

shippingMethod

string

Shipping method: standard, express, overnight, or pickup

trackingNumber

string

Shipping carrier tracking number

shippingCarrier

string

Carrier name: servientrega, coordinadora, tcc, deprisa, or pickup

orderDate

string

ISO 8601 timestamp when order was created

estimatedDeliveryDate

string

ISO 8601 timestamp for estimated delivery

deliveredDate

string

ISO 8601 timestamp when order was delivered (null if not yet delivered)

statusHistory

array

Array of status change records

Show history item structure

status

string

Status value

date

string

ISO 8601 timestamp of change

note

string

Optional note about the change

updatedBy

string

User ID who made the change

Get User Orders

Headers

Authorization

string

required

Bearer token: Bearer YOUR_JWT_TOKEN

Query Parameters

status

string

Filter by order status (e.g., pending, shipped, delivered)

page

integer

default:"1"

Page number for pagination

limit

integer

default:"10"

Number of orders per page

sortBy

string

default:"newest"

Sort order: newest (newest first) or oldest (oldest first)

Response

curl -X GET "https://api.fitaiid.com/api/orders?status=shipped&limit=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Order by ID

Path Parameters

string

required

Order ID or order number (MongoDB ObjectId or order number like “2024-03-0001”)

Response

curl -X GET https://api.fitaiid.com/api/orders/2024-03-0001 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Order Status

This endpoint requires admin privileges. Status transitions are validated to prevent invalid state changes.

Path Parameters

string

required

Order ID (MongoDB ObjectId)

Body Parameters

status

string

required

New order status

Show valid transitions

From pending: Can change to confirmed or cancelled
From confirmed: Can change to processing or cancelled
From processing: Can change to shipped or cancelled
From shipped: Can change to delivered or returned
From delivered: Can change to returned
cancelled and returned are final states

note

string

Optional note about the status change (max 500 characters)

trackingNumber

string

Tracking number (required when changing status to shipped)

shippingCarrier

string

Carrier name (required when changing status to shipped)

Response

curl -X PUT https://api.fitaiid.com/api/orders/65f1234567890abcdef12345/status \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "note": "Pedido enviado con Servientrega",
    "trackingNumber": "SER123456789CO",
    "shippingCarrier": "servientrega"
  }'

Cancel Order

Orders can only be cancelled if they are in pending, confirmed, or processing status. Shipped or delivered orders cannot be cancelled.

Path Parameters

string

required

Order ID (MongoDB ObjectId)

Body Parameters

reason

string

Reason for cancellation (max 500 characters)

Response

curl -X POST https://api.fitaiid.com/api/orders/65f1234567890abcdef12345/cancel \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Changed my mind about the purchase"
  }'

Track Order

Path Parameters

string

required

Order ID or order number

Response

curl -X GET https://api.fitaiid.com/api/orders/2024-03-0001/tracking \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Order Statistics

This endpoint requires admin privileges.

Query Parameters

dateFrom

string

Start date for statistics (ISO 8601 format)

dateTo

string

End date for statistics (ISO 8601 format)

Response

curl -X GET "https://api.fitaiid.com/api/orders/stats?dateFrom=2024-01-01&dateTo=2024-03-31" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"

Error Responses

400 Bad Request

Invalid request parameters

Show examples

{
  "success": false,
  "error": {
    "message": "No se puede cambiar de shipped a pending",
    "statusCode": 400
  }
}

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

User does not have permission to access this order or requires admin privileges

404 Not Found

Order not found

Show example

{
  "success": false,
  "error": {
    "message": "Pedido no encontrado",
    "statusCode": 404
  }
}

Webhooks

Order Status Change Webhook

Configure webhooks to receive real-time notifications when order status changes. See the Webhooks documentation for setup instructions.

Webhook Payload Example

{
  "event": "order.status_changed",
  "timestamp": "2024-03-02T09:00:00.000Z",
  "data": {
    "orderId": "65f1234567890abcdef12345",
    "orderNumber": "2024-03-0001",
    "previousStatus": "processing",
    "newStatus": "shipped",
    "trackingNumber": "SER123456789CO",
    "user": {
      "id": "507f191e810c19729de860ea",
      "email": "[email protected]"
    }
  }
}

Authentication

Workouts

User Management

Notifications

Payments

Overview

Order Object

Get User Orders

Headers

Query Parameters

Response

Get Order by ID

Path Parameters

Response

Update Order Status

Path Parameters

Body Parameters

Response

Cancel Order

Path Parameters

Body Parameters

Response

Track Order

Path Parameters

Response

Get Order Statistics

Query Parameters

Response

Error Responses

Webhooks

Order Status Change Webhook

Webhook Payload Example

Build docs developers (and LLMs) love

Authentication

Workouts

User Management

Notifications

Payments

​Overview

​Order Object

​Get User Orders

​Headers

​Query Parameters

​Response

​Get Order by ID

​Path Parameters

​Response

​Update Order Status

​Path Parameters

​Body Parameters

​Response

​Cancel Order

​Path Parameters

​Body Parameters

​Response

​Track Order

​Path Parameters

​Response

​Get Order Statistics

​Query Parameters

​Response

​Error Responses

​Webhooks

Order Status Change Webhook

​Webhook Payload Example

Build docs developers (and LLMs) love

Overview

Order Object

Get User Orders

Headers

Query Parameters

Response

Get Order by ID

Path Parameters

Response

Update Order Status

Path Parameters

Body Parameters

Response

Cancel Order

Path Parameters

Body Parameters

Response

Track Order

Path Parameters

Response

Get Order Statistics

Query Parameters

Response

Error Responses

Webhooks

Webhook Payload Example