Orders

Endpoint reference: ✅ Verified live against production on 10 May 2026. Orders are the conversion event in your store — when a customer’s cart becomes a purchase. The Dr Green admin team manually approves each order before it ships, so expect an asynchronous lifecycle: place → pending → admin-verified → paid → shipped.

Order lifecycle (the high-level flow)

[Customer checks out]
    │
    ▼
POST /dapp/orders            ← your store's call
    │
    ▼
order.orderStatus = PENDING
order.adminApproval = PENDING
order.paymentStatus = PENDING
    │
    ▼
[Dr Green admin reviews]      ← manual, hours to days
    │
    ├── REJECTED → adminApproval=REJECTED  (terminal — refund, notify customer)
    └── VERIFIED → adminApproval=VERIFIED
                   ▼
              [Customer pays via processor]
                   ▼
              paymentStatus = COMPLETED
                   ▼
              [Dr Green ships]   (no separate shipped status currently surfaced)

There’s no outbound webhook for status changes — your store must poll. See 06-webhooks.md § The polling pattern.

Endpoints

Method	Path	Auth	Description
`POST`	`/dapp/orders`	API-key + sig	Create a new order from a cart
`GET`	`/dapp/orders`	API-key + sig	List orders, paginated
`GET`	`/dapp/orders/recent`	API-key + sig	Recently-created orders (heartbeat polling target)
`GET`	`/dapp/orders/summary`	API-key + sig	Order status counts
`GET`	`/dapp/orders/chart-data`	API-key + sig	Time-series, requires date range
`GET`	`/dapp/orders/status-breakdown`	API-key + sig	Status breakdown over date range
`GET`	`/dapp/orders/{orderId}`	API-key + sig	Full order detail

Status enums

Field	Values	Set by
`orderStatus`	`PENDING`, `PROCESSING`, `SHIPPED`, `DELIVERED`, `CANCELLED`	Server-side based on lifecycle
`adminApproval`	`PENDING`, `VERIFIED`, `REJECTED`	Dr Green admin
`paymentStatus`	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REFUNDED`	Payment processor webhook

🔒 The complete enum lists above are inferred from observed values (PENDING, VERIFIED, REJECTED confirmed live). Other values are likely supported but not yet captured. Defensively handle unknown statuses — render them as the raw string.

`POST /dapp/orders` — create an order

Creates an order from explicit line items + shipping + (optionally) the cart it came from. The shipping address must be one of the client’s shippings[] (referenced by id).

Request body

The shape follows CreateOrderDto. Verified pattern:

{
  "clientId": "2cbab026-9dc6-46fd-8580-77e3dfd2f086",
  "shippingId": "167d30ee-52d1-48eb-b501-b1203ad72074",
  "orderLines": [
    { "strainId": "c77dd198-ec9a-4ced-8105-937fde104424", "quantity": 1 }
  ],
  "paymentMethod": "CRYPTO"
}

Field	Type	Required	Notes
`clientId`	string (UUID)	✅	Must be `adminApproval=VERIFIED`, `isKYCVerified=true`, `isActive=true`
`shippingId`	string (UUID)	✅	One of `client.shippings[].id`
`orderLines`	array	✅	At least one line
`orderLines[].strainId`	string (UUID)	✅
`orderLines[].quantity`	integer	✅	Grams; positive integer
`paymentMethod`	string	✅	`CRYPTO` (CoinRemitter), `FIAT` (Payinn), `PGPAY` (PGPay) — confirm with Dr Green which are enabled per country
`cartId`	string (UUID)	No	Reference to the cart that fed this order, if any
`notes`	string	No	Free-text

Canonical payload (for signing)

JSON.stringify(body) — compact, no whitespace.

Response

201 Created with the order’s id and invoiceNumber. The invoiceNumber is a 32-char random string Dr Green generates server-side — use it as your customer-facing reference. Don’t generate your own.

{
  "success": true,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "603b3f1a-4cab-44af-972d-a26a77fbdff9",
    "invoiceNumber": "XUnt8v3wYkUWcTEEKeuYtPz1ia0SBNmN",
    "totalAmount": 9.09,
    "orderStatus": "PENDING",
    "adminApproval": "PENDING",
    "paymentStatus": "PENDING"
  }
}

Idempotency warning

POST /dapp/orders is not idempotent. A retry creates a duplicate order. Two patterns to avoid this: Pattern 1 — pre-flight check. Before any retry, query GET /dapp/orders?page=1&limit=20 and look for a recent order matching the customer + total amount. If found, treat your original POST as having succeeded. Pattern 2 — your-side correlation ID. Generate a UUID at checkout, store order_in_flight: <uuid> in your store DB, only POST once. On any retry, check if the previous attempt eventually returned a 2xx (which you’d have logged) before retrying. See 04-errors.md § Idempotency for the full discussion.

Errors

Status	Cause	Fix
`400` `["clientId must be a UUID"]`	Validation	Validate input
`400` “Client not verified” / similar	Client isn’t `VERIFIED + KYC + active`	Surface to customer; can’t recover
`400` “Shipping not found for client”	`shippingId` doesn’t belong to this client	Re-fetch client and use a valid shipping `id`
`400` “Strain not available in client’s country”	Strain `availableCountries` doesn’t include client’s country	Filter strains to client’s country before placing order

`GET /dapp/orders` — list orders

Paginated list of all orders for the holder.

Query parameters

Name	Type	Default	Notes
`page`	integer	`1`
`limit`	integer	`10`
`status`	string	—	Filter by `orderStatus`
`adminApproval`	string	—	Filter by `adminApproval`
`clientId`	string (UUID)	—	Filter to one client (or use `/dapp/client/{id}/orders`)
`search`	string	—	Free-text on `invoiceNumber`

Response shape (verified)

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "orders": [
      {
        "id": "603b3f1a-4cab-44af-972d-a26a77fbdff9",
        "invoiceNumber": "XUnt8v3wYkUWcTEEKeuYtPz1ia0SBNmN",
        "orderStatus": "PENDING",
        "adminApproval": "VERIFIED",
        "paymentStatus": "PENDING",
        "totalAmount": 9.09,
        "shipping": {
          "country": "South Africa",
          "countryCode": "ZAF",
          "currency": null
        },
        "transactions": [],
        "createdAt": "2025-05-12T17:29:57.100Z",
        "nft": { "tokenId": 56, "ownerId": "0x553374bd..." },
        "client": {
          "id": "f1281910-f463-4da9-92c0-feb81a9db994",
          "firstName": "Jacques",
          "lastName": "De Reuck",
          "shippings": [ { "countryCode": "ZAF" } ]
        },
        "_count": { "orderLines": 1 },
        "totalQuantity": 1,
        "totalPrice": 9.09,
        "localPrice": { "currency": "ZAR", "totalAmount": 165 }
      }
    ],
    "pageMetaDto": { "page": "1", "take": 10, "itemCount": 21, "pageCount": 3, "hasPreviousPage": false, "hasNextPage": true }
  }
}

🪲 _count is a Prisma-leaked field — it’s { orderLines: <count> }. Treat it as informational, not authoritative.

🪲 totalAmount, totalPrice, and localPrice.totalAmount are different things:

totalAmount and totalPrice are the same USD figure (mirroring of fields)

localPrice.totalAmount is the customer-currency equivalent (e.g. ZAR for South Africa) Use localPrice for display, totalAmount for accounting.

`GET /dapp/orders/recent` — recent orders

Same shape as GET /dapp/orders but always returns the most recent 10 (no pagination needed). Use this as a heartbeat polling target — cheap call that surfaces anything new across all customers.

Canonical payload

{}

`GET /dapp/orders/summary` — status counts

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "summary": {
      "PENDING": 0,
      "VERIFIED": 11,
      "REJECTED": 10,
      "totalCount": 21
    }
  }
}

The keys are adminApproval values (not orderStatus). For an orderStatus breakdown over time, use /dapp/orders/status-breakdown with a date range.

`GET /dapp/orders/chart-data` and `/status-breakdown`

Both require startDate and endDate in YYYY-MM-DD format. Without them: 400.

Canonical payload (with date range)

startDate=2026-04-01&endDate=2026-05-01 🔒 Response shapes pending live capture with valid date ranges.

`GET /dapp/orders/{orderId}` — order detail

Full detail including line items with embedded strain info, transactions, and the multi-currency price breakdown.

Canonical payload

{}

Response shape (verified)

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "orderDetails": {
      "id": "603b3f1a-4cab-44af-972d-a26a77fbdff9",
      "invoiceNumber": "XUnt8v3wYkUWcTEEKeuYtPz1ia0SBNmN",
      "orderStatus": "PENDING",
      "paymentStatus": "PENDING",
      "totalAmount": 9.09,
      "deliveryFee": 6,
      "totalProfit": 3.59,
      "totalOrdered": 1,
      "totalQuantity": 1,
      "createdAt": "2025-05-12T17:29:57.100Z",
      "updatedAt": "2025-05-13T13:05:08.284Z",
      "transactions": [],
      "nft": { "tokenId": 56, "ownerId": "0x553374bd..." },
      "client": {
        "id": "f1281910-f463-4da9-92c0-feb81a9db994",
        "firstName": "Jacques",
        "lastName": "De Reuck",
        "phoneCode": "+27",
        "contactNumber": "832854483",
        "shippings": [ /* full shipping details */ ]
      },
      "orderLines": [
        {
          "quantity": 1,
          "strain": {
            "id": "c77dd198-ec9a-4ced-8105-937fde104424",
            "name": "Femme Fatale",
            "imageUrl": "33eac80b-58c4-46d3-a82b-b70c875d333f-cakes-and-cream.png"
          }
        }
      ],
      "localPrice": {
        "currency": "ZAR",
        "totalAmount": 165,
        "totalProfit": 66,
        "wholeSalePrice": 99,
        "retailPrice": 165,
        "location": {
          "country": "South Africa",
          "currency": "ZAR"
        }
      }
    }
  }
}

⚠️ The order detail wraps the data inside an extra orderDetails field — i.e. data.orderDetails, not data directly. Other endpoints don’t wrap like this. Mind the inconsistency.

🪲 totalAmount is in USD, localPrice.totalAmount is in the customer’s local currency. Don’t render totalAmount to the customer — use localPrice.totalAmount with localPrice.currency.

🪲 totalOrdered and totalQuantity are the same number in observed responses. The duplication is a backend wart.

Common patterns

Polling order status

async def poll_order_until_terminal(order_id: str):
    terminal = {"DELIVERED", "CANCELLED"}
    while True:
        order = await get_order(order_id)
        details = order["orderDetails"]
        if details["orderStatus"] in terminal or details["adminApproval"] == "REJECTED":
            return details
        await asyncio.sleep(60 + random.uniform(-6, 6))  # 60s ± 10% jitter

Surface multi-currency totals

function displayTotal(order: OrderDetails): string {
  const lp = order.localPrice;
  if (lp?.currency && lp.totalAmount != null) {
    return new Intl.NumberFormat(undefined, { style: 'currency', currency: lp.currency }).format(lp.totalAmount);
  }
  return `$${order.totalAmount.toFixed(2)} USD`;
}

Detecting status changes between polls

function statusFingerprint(o: OrderDetails): string {
  return `${o.orderStatus}|${o.adminApproval}|${o.paymentStatus}`;
}
// Fire customer notifications only when fingerprint changes

Caching guidance

Resource	TTL	Rationale
Active order detail	30s	Customer expects ~real-time feel
Terminal-status order detail	5m	Doesn’t change
Order list (paginated)	No cache	Always fresh
Order summary counts	1m	Dashboards

Getting Started

Core Concepts

Guides

Endpoint Reference

Orders

Orders

Order lifecycle (the high-level flow)

Endpoints

Status enums

`POST /dapp/orders` — create an order

Request body

Canonical payload (for signing)

Response

Idempotency warning

Errors

`GET /dapp/orders` — list orders

Query parameters

Response shape (verified)

`GET /dapp/orders/recent` — recent orders

Canonical payload

`GET /dapp/orders/summary` — status counts

`GET /dapp/orders/chart-data` and `/status-breakdown`

Canonical payload (with date range)

`GET /dapp/orders/{orderId}` — order detail

Canonical payload

Response shape (verified)

Common patterns

Polling order status

Surface multi-currency totals

Detecting status changes between polls

Caching guidance

See also

Getting Started

Core Concepts

Guides

Endpoint Reference

Documentation Index

​Orders

​Order lifecycle (the high-level flow)

​Endpoints

​Status enums

​POST /dapp/orders — create an order

​Request body

​Canonical payload (for signing)

​Response

​Idempotency warning

​Errors

​GET /dapp/orders — list orders

​Query parameters

​Response shape (verified)

​GET /dapp/orders/recent — recent orders

​Canonical payload

​GET /dapp/orders/summary — status counts

​GET /dapp/orders/chart-data and /status-breakdown

​Canonical payload (with date range)

​GET /dapp/orders/{orderId} — order detail

​Canonical payload

​Response shape (verified)

​Common patterns

​Polling order status

​Surface multi-currency totals

​Detecting status changes between polls

​Caching guidance

​See also

Orders

Order lifecycle (the high-level flow)

Endpoints

Status enums

`POST /dapp/orders` — create an order

Request body

Canonical payload (for signing)

Response

Idempotency warning

Errors

`GET /dapp/orders` — list orders

Query parameters

Response shape (verified)

`GET /dapp/orders/recent` — recent orders

Canonical payload

`GET /dapp/orders/summary` — status counts

`GET /dapp/orders/chart-data` and `/status-breakdown`

Canonical payload (with date range)

`GET /dapp/orders/{orderId}` — order detail

Canonical payload

Response shape (verified)

Common patterns

Polling order status

Surface multi-currency totals

Detecting status changes between polls

Caching guidance

See also