Orders API: create, list, and update order status

The orders API covers the full lifecycle of a Krafta print-on-demand order: a customer submits their design, shipping details, and payment evidence in a single POST; the ADMIN or workshop (TALLER) team then retrieves the order list via GET and advances its status through the production pipeline via PUT. Orders are identified by a sequential human-readable number in the format KRFT-XXXXXX.

POST /api/orders

Creates a new order. The endpoint accepts the chosen product variant, shipping details, pricing snapshot, design identifiers, and a payment submission in one request body. Authentication is optional: if a valid krafta-token cookie is present the order is linked to the authenticated user; otherwise it is recorded under a fallback guest identifier. On success the order is persisted to the database with status: "REPORTED", meaning Krafta staff must verify the payment before production begins. If the database is unavailable the order falls back to a local JSON file in public/orders/.

Request body

variantId

string

required

The ID of the ProductVariant the customer is ordering (e.g. "var-1").

quantity

number

required

Number of units ordered.

shippingAddress

string

required

Street address for delivery (e.g. "Av. Libertador 123").

shippingCity

string

required

Destination city (e.g. "Barquisimeto").

shippingState

string

required

Destination state (e.g. "Lara").

shippingCost

number

required

Shipping cost in USD (e.g. 3.00).

subtotal

number

required

Product subtotal in USD before shipping (e.g. 12.00).

total

number

required

Total amount charged in USD including shipping (e.g. 15.00).

totalBs

number

required

Total amount in Venezuelan bolívares at the time of checkout (e.g. 600.00).

exchangeRate

number

required

USD → VES exchange rate used to compute totalBs (e.g. 40.00).

designUploadId

string

UUID of the DesignUpload record referencing the customer’s artwork file. Pass null or omit if no upload was made.

previewUrl

string

A URL or data URI for the design preview image generated by the on-canvas editor.

viewDesigns

array

Array of per-view design configuration objects captured by the editor. Stored as JSON in designViewsJson on the OrderItem.

payment

object

required

Payment submission details reported by the customer.

Show payment fields

method

string

required

Payment method used. Typical values: "PAGO_MOVIL", "TRANSFERENCIA".

amountReported

number

required

Amount the customer claims to have transferred, in bolívares (e.g. 600.00).

reference

string

required

Bank transaction reference number (e.g. "12345678").

originBank

string

required

Name of the bank from which the transfer was made (e.g. "Banesco").

payerName

string

required

Full name of the account holder who sent the payment (e.g. "Juan Pérez").

receiptUrl

string

required

Path or URL to the uploaded payment receipt image (e.g. "/uploads/user/receipt.jpg").

{
  "variantId": "var-1",
  "quantity": 1,
  "shippingAddress": "Av. Libertador 123",
  "shippingCity": "Barquisimeto",
  "shippingState": "Lara",
  "shippingCost": 3.00,
  "subtotal": 12.00,
  "total": 15.00,
  "totalBs": 600.00,
  "exchangeRate": 40.00,
  "designUploadId": "d5e6f7a8-...",
  "previewUrl": "/uploads/previews/preview-abc.jpg",
  "viewDesigns": [],
  "payment": {
    "method": "PAGO_MOVIL",
    "amountReported": 600.00,
    "reference": "12345678",
    "originBank": "Banesco",
    "payerName": "Juan Pérez",
    "receiptUrl": "/uploads/user/receipt.jpg"
  }
}

Response

success

boolean

true when the order is created.

orderId

string

UUID of the newly created order, used for internal references and status updates.

orderNumber

string

Human-readable order identifier shown to the customer. Format: KRFT-XXXXXX where XXXXXX is a six-digit random number (e.g. "KRFT-482031").

{
  "success": true,
  "orderId": "f1e2d3c4-b5a6-...",
  "orderNumber": "KRFT-482031"
}

The order’s initial status is always REPORTED. The customer’s payment has not yet been verified by Krafta staff. Production does not begin until an ADMIN advances the status to CONFIRMED.

GET /api/orders

Returns all orders sorted by creation date descending. Each order includes its full items and payments arrays. This endpoint is intended for the internal admin dashboard and workshop management panel. This endpoint does not enforce authentication at the route level — it is the caller’s responsibility to protect any UI that surfaces this data. In practice, the admin and workshop dashboards that consume it are themselves behind role-gated page guards.

Response

success

boolean

true on a successful fetch.

orders

array

Array of order objects, each containing the full order record with nested items and payments.

Show order fields

string

The order’s UUID.

orderNumber

string

Human-readable order number (e.g. "KRFT-482031").

userId

string

UUID of the user who placed the order.

status

string

Current order status. See the PUT endpoint for the full list of valid values.

shippingAddress

string

Delivery street address.

shippingCity

string

Delivery city.

shippingState

string

Delivery state.

subtotal

number

Product subtotal in USD.

total

number

Total charged in USD.

totalBs

number

Total in bolívares at checkout.

exchangeRate

number

Exchange rate used at checkout.

createdAt

string

ISO 8601 timestamp of order creation.

items

array

Array of OrderItem records for this order.

payments

array

Array of PaymentSubmission records associated with this order.

{
  "success": true,
  "orders": [
    {
      "id": "f1e2d3c4-...",
      "orderNumber": "KRFT-482031",
      "userId": "a1b2c3d4-...",
      "status": "REPORTED",
      "shippingAddress": "Av. Libertador 123",
      "shippingCity": "Barquisimeto",
      "shippingState": "Lara",
      "shippingCost": 3,
      "subtotal": 12,
      "total": 15,
      "totalBs": 600,
      "exchangeRate": 40,
      "createdAt": "2024-07-01T10:30:00.000Z",
      "items": [
        {
          "id": "item-uuid",
          "quantity": 1,
          "price": 12,
          "cost": 7.2,
          "previewUrl": "/uploads/previews/preview-abc.jpg"
        }
      ],
      "payments": [
        {
          "id": "pay-uuid",
          "method": "PAGO_MOVIL",
          "amountReported": 600,
          "reference": "12345678",
          "status": "REPORTED"
        }
      ]
    }
  ]
}

PUT /api/orders

Advances an order to a new status in the production lifecycle. Requires the ADMIN or TALLER role.

Request body

orderId

string

required

The UUID of the order to update (the id field, not the orderNumber).

status

string

required

The target status. Must be one of the values in the table below.

Valid status values

Value	Meaning
`CONFIRMED`	Payment has been verified by an admin; order enters production queue
`IN_PRODUCTION`	Workshop has started printing/producing the order
`READY`	Production complete; order is ready for pickup or dispatch
`HANDED_TO_DELIVERY`	Order handed off to a courier or delivery partner
`COMPLETED`	Order delivered and closed
`CANCELLED`	Order cancelled by admin or customer request

{
  "orderId": "f1e2d3c4-b5a6-...",
  "status": "CONFIRMED"
}

Response

success

boolean

true when the status update is applied.

{
  "success": true
}

Error responses

Status	Condition
`400`	`orderId` or `status` is missing from the request body
`403`	The request does not carry a valid `ADMIN` or `TALLER` session
`404`	No order with the given `orderId` was found in the local filesystem fallback (returned only when the database update also fails)

Authentication

Endpoints

Orders API: create, list, and update order status

POST /api/orders

Request body

Response

GET /api/orders

Response

PUT /api/orders

Request body

Valid status values

Response

Error responses

Build docs developers (and LLMs) love

Authentication

Endpoints

Documentation Index

​POST /api/orders

​Request body

​Response

​GET /api/orders

​Response

​PUT /api/orders

​Request body

​Valid status values

​Response

​Error responses

Build docs developers (and LLMs) love

POST /api/orders

Request body

Response

GET /api/orders

Response

PUT /api/orders

Request body

Valid status values

Response

Error responses