Data Models in the Panahashi API

Every object returned by the Panahashi API maps directly to a Kotlin data class defined in Models.kt and stored as a Firestore document. All timestamps are Unix epoch milliseconds (Long). All monetary amounts are Double values in Colombian pesos (COP). The sections below document each model’s fields, the enum values they reference, and example JSON for the most commonly used types.

Enums

UserRole

Determines what API endpoints a user can access.

Value	Description
`CUSTOMER`	Default role. Can place orders, manage cart, and write reviews.
`BAKER`	Manages a single bakery’s products and orders.
`ADMIN`	Full platform access including role management and refunds.

BakeryStatus

Controls whether a bakery is visible and operational.

Value	Description
`ACTIVE`	Bakery is live and visible to customers.
`INACTIVE`	Bakery is not yet published or has been deactivated.
`SUSPENDED`	Bakery has been suspended by an admin.

ProductAvailabilityStatus

Indicates when a product can be picked up.

Value	Description
`READY_NOW`	Available immediately.
`READY_IN_20`	Ready in approximately 20 minutes.
`READY_IN_60`	Ready in approximately 60 minutes.
`ADVANCE_ORDER_ONLY`	Must be ordered in advance. See `advanceMinutes`.
`OUT_OF_STOCK`	Not currently available.

OrderStatus

Tracks an order through its lifecycle.

Value	Description
`PENDING`	Order placed but not yet confirmed by the bakery.
`CONFIRMED`	Bakery has accepted the order.
`BAKING`	Order is being prepared.
`READY`	Order is ready for pickup.
`COMPLETED`	Customer has picked up the order.
`CANCELLED`	Order was cancelled.

PaymentStatus

Tracks payment state for an order.

Value	Description
`PENDING`	Payment has not yet been processed.
`APPROVED`	Payment was successful.
`REJECTED`	Payment was declined.
`REFUNDED`	Payment has been refunded by an admin.

PaymentMethod

The method used to pay for an order.

Value	Description
`CREDIT_CARD`	Simulated credit card payment.
`DEBIT_CARD`	Simulated debit card payment.
`PSE`	Colombian online bank transfer (PSE).
`CASH_ON_PICKUP`	Customer pays with cash at pickup.

PromotionType

Determines how a discount is calculated.

Value	Description
`PERCENTAGE`	Discount as a percentage of the order total. Uses `discountPct`.
`FIXED_AMOUNT`	Flat amount deducted from the total. Uses `discountAmount`.
`HAPPY_HOUR`	Discount active only between `happyHourStart` and `happyHourEnd`.

Bakery

Represents a bakery on the platform.

string

required

Firestore document ID. Auto-generated on creation.

name

string

required

Display name of the bakery.

description

string

Short description shown on the bakery’s profile page.

address

string

Street address for pickup.

lat

number

Latitude coordinate used for the nearby bakeries query.

lng

number

Longitude coordinate used for the nearby bakeries query.

phone

string

Contact phone number.

logoUrl

string

URL of the bakery’s logo image.

bannerUrl

string

URL of the bakery’s banner image.

isOpen

boolean

Whether the bakery is currently accepting orders.

openTime

string

Opening time in HH:mm format. Default "07:00".

closeTime

string

Closing time in HH:mm format. Default "20:00".

rating

number

Average review rating, recalculated on each new review submission.

totalReviews

number

Total number of reviews submitted for this bakery.

status

BakeryStatus

One of ACTIVE, INACTIVE, or SUSPENDED. Default INACTIVE.

ownerId

string

Firebase UID of the BAKER user who owns this bakery.

createdAt

number

Unix epoch milliseconds when the bakery was created.

Product

Represents a baked good offered by a bakery.

string

required

Firestore document ID.

bakeryId

string

required

ID of the bakery that owns this product.

name

string

required

Display name of the product.

price

number

required

Price in COP.

emoji

string

Single emoji character used as a quick visual indicator.

availabilityStatus

ProductAvailabilityStatus

One of READY_NOW, READY_IN_20, READY_IN_60, ADVANCE_ORDER_ONLY, or OUT_OF_STOCK. Default READY_NOW.

stock

number

Current units in stock.

Order

Tracks a customer order from placement through pickup.

string

required

Firestore document ID.

userId

string

required

Firebase UID of the customer who placed the order.

userName

string

Display name of the customer at the time of order.

bakeryId

string

required

ID of the bakery fulfilling the order.

bakeryName

string

Display name of the bakery at the time of order.

items

CartItem[]

Snapshot of the items in the order. See CartItem below.

total

number

Final order total in COP, after any discount.

status

OrderStatus

Lifecycle status. One of PENDING, CONFIRMED, BAKING, READY, COMPLETED, CANCELLED.

createdAt

number

Unix epoch milliseconds when the order was placed.

pickupTime

string

Human-readable pickup time string (e.g. "15:30").

scheduledFor

number | null

Unix epoch milliseconds for scheduled advance orders. null for immediate orders.

qrCode

string

QR code payload used by bakers to verify pickup via POST /api/v1/orders/verify-qr.

notes

string

Customer notes for the bakery (e.g. "Sin azúcar").

estimatedReadyAt

number | null

Unix epoch milliseconds when the order is expected to be ready. Set by the baker.

discountAmount

number

Amount deducted by a promotion, in COP. 0 if no promotion applied.

promotionId

string | null

ID of the applied promotion, or null if none.

paymentStatus

PaymentStatus

One of PENDING, APPROVED, REJECTED, REFUNDED.

paymentMethod

PaymentMethod

One of CREDIT_CARD, DEBIT_CARD, PSE, CASH_ON_PICKUP.

Example Order

{
  "id": "order-abc123",
  "userId": "firebase-uid-abc123",
  "userName": "María López",
  "bakeryId": "bakery-xyz789",
  "bakeryName": "La Panadería Feliz",
  "items": [
    { "productId": "prod-001", "name": "Croissant de mantequilla", "price": 4500, "emoji": "🥐", "qty": 2 }
  ],
  "total": 9000,
  "status": "CONFIRMED",
  "createdAt": 1716000000000,
  "pickupTime": "15:30",
  "scheduledFor": null,
  "qrCode": "QR-order-abc123",
  "notes": "",
  "estimatedReadyAt": 1716001800000,
  "discountAmount": 0,
  "promotionId": null,
  "paymentStatus": "APPROVED",
  "paymentMethod": "CREDIT_CARD"
}

CartItem

A snapshot of a product at the time it is added to an order. Embedded inside Order.items.

productId

string

ID of the source product.

name

string

Product name at the time the item was added.

price

number

Unit price in COP at the time the item was added.

emoji

string

Product emoji at the time the item was added.

qty

number

Quantity ordered.

UserProfile

Stores metadata for an authenticated user in the users Firestore collection.

uid

string

required

Firebase UID. Used as the Firestore document ID.

displayName

string

User’s display name from Firebase Auth.

string

User’s email address.

phone

string

Contact phone number.

role

UserRole

One of CUSTOMER, BAKER, or ADMIN. Default CUSTOMER.

bakeryId

string

ID of the bakery linked to this user. Non-empty only for BAKER users.

fcmToken

string

Firebase Cloud Messaging token for push notifications.

createdAt

number

Unix epoch milliseconds when the profile was created.

Payment

Records a payment transaction for an order.

string

required

Firestore document ID.

orderId

string

required

ID of the order this payment belongs to.

userId

string

required

Firebase UID of the paying customer.

amount

number

Amount charged in COP.

method

PaymentMethod

One of CREDIT_CARD, DEBIT_CARD, PSE, CASH_ON_PICKUP.

status

PaymentStatus

One of PENDING, APPROVED, REJECTED, REFUNDED.

simulatedCardLast4

string

Last four digits of the simulated card, used for display in the client. Empty for non-card methods.

createdAt

number

Unix epoch milliseconds when the payment record was created.

updatedAt

number

Unix epoch milliseconds when the payment record was last updated (e.g. after a refund).

Review

A customer review submitted after a completed order.

string

required

Firestore document ID.

bakeryId

string

required

ID of the bakery being reviewed.

userId

string

required

Firebase UID of the reviewer.

userName

string

Display name of the reviewer at the time of submission.

orderId

string

ID of the completed order associated with this review.

rating

number

Integer rating from 1 to 5.

comment

string

Free-text review body.

createdAt

number

Unix epoch milliseconds when the review was submitted.

LoyaltyCard

Tracks a customer’s stamp-card progress at a specific bakery.

string

required

Firestore document ID.

userId

string

required

Firebase UID of the card holder.

bakeryId

string

required

ID of the bakery this card belongs to.

stamps

number

Current stamp count toward the next reward.

stampsForReward

number

Number of stamps required to earn one free item. Default 9.

totalRewardsEarned

number

Cumulative number of rewards earned across all time.

freeItemsAvailable

number

Number of unredeemed free items the customer can claim.

updatedAt

number

Unix epoch milliseconds when the card was last updated.

Promotion

A discount applied to an order at checkout.

string

required

Firestore document ID.

bakeryId

string

required

ID of the bakery that created this promotion.

productId

string

ID of the specific product this promotion applies to. Empty string if bakery-wide.

title

string

Short display name shown in the client.

description

string

Longer explanation of the promotion terms.

type

PromotionType

One of PERCENTAGE, FIXED_AMOUNT, or HAPPY_HOUR.

discountPct

number

Percentage discount (0–100). Used when type is PERCENTAGE.

discountAmount

number

Fixed discount in COP. Used when type is FIXED_AMOUNT.

happyHourStart

string

Happy hour start time in HH:mm format. Used when type is HAPPY_HOUR.

happyHourEnd

string

Happy hour end time in HH:mm format. Used when type is HAPPY_HOUR.

active

boolean

Whether the promotion is currently live. Default true.

createdAt

number

Unix epoch milliseconds when the promotion was created.

Response wrappers

All Panahashi endpoints return data wrapped in one of two envelope types.

ApiResponse<T>

Used for single-object and action responses.

success

boolean

required

true if the request succeeded, false on error.

data

T | null

The response payload. null on error responses.

message

string | null

Human-readable message. Present on errors and some success responses.

Example ApiResponse

{
  "success": true,
  "data": {
    "id": "order-abc123",
    "status": "CONFIRMED"
  },
  "message": null
}

PagedResponse<T>

Used for list endpoints that support pagination.

data

T[]

required

The current page of results.

page

number

required

Current page index (1-based).

pageSize

number

required

Number of items per page.

total

number

required

Total number of items across all pages.

hasMore

boolean

required

true if there are additional pages beyond the current one.

Example PagedResponse

{
  "data": [ { "id": "prod-001", "name": "Croissant de mantequilla" } ],
  "page": 1,
  "pageSize": 20,
  "total": 47,
  "hasMore": true
}

To fetch the next page, increment the page query parameter by 1 and repeat the request with the same pageSize.

Get Started

Core Concepts

Guides

Data Models in the Panahashi API

Enums

Bakery

Product

Order

CartItem

UserProfile

Payment

Review

LoyaltyCard

Promotion

Response wrappers

ApiResponse<T>

PagedResponse<T>

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Enums

​Bakery

​Product

​Order

​CartItem

​UserProfile

​Payment

​Review

​LoyaltyCard

​Promotion

​Response wrappers

​ApiResponse<T>

​PagedResponse<T>

Build docs developers (and LLMs) love

Enums

Bakery

Product

Order

CartItem

UserProfile

Payment

Review

LoyaltyCard

Promotion

Response wrappers

ApiResponse<T>

PagedResponse<T>