Privacy and analytics

We use necessary technical cookies and, only with your consent, analytics and marketing pixels to improve the website and measure campaigns.

English

Español English Français Deutsch Italiano Português

Reference5 min read

Orders

Orders with their payment plan and paying each installment, without card data.

On this page

orders.list · List orders
orders.screen.list · Orders (screen)
orders.screen.get · One order (screen)
orders.installments.start · Pay an installment

orders.list · List orders

Brand orders with status, date and total. No payment ids, card data or customer emails.

Field	Value
Kind	Read
HTTP method	`POST /api/v1/orders.list`
MCP tool	`orders_list`
Scope	`orders.read`
Minimum role	Billing
Human confirmation	No
Doors	Nödo, Voice, MCP, API, Chat, Screens, Apps
Status	Available
Widget	`list`

Input

{
  cursor?: string  // ≤ 512 · Opaque cursor from a previous `nextCursor`.
  limit?: integer  // 1–50 · default 20
}

Output

{
  items: Array<{
    id: string  // uuid
    number: string
    status: string
    total: number
    currency: string
    createdAt: string
  }>
  nextCursor: string | null
}

orders.screen.list · Orders (screen)

The brand's orders, newest first: number, concept, total with VAT, what is paid, and the payment plan as installments (one per payment step of its works, or a single one) with each state. filter: due (something to pay or overdue), paid, refunded. Pages by offset/limit (max 50). For a compact list use orders.list.

Field	Value
Kind	Read
HTTP method	`POST /api/v1/orders.screen.list`
MCP tool	`orders_screen_list`
Scope	`orders.read`
Minimum role	Billing
Human confirmation	No
Doors	API, MCP, Screens, Apps, Nödo
Status	Available

Input

{
  filter?: "all" | "due" | "paid" | "refunded"
  offset?: integer  // 0–100000
  limit?: integer  // 1–50
}

Output

{
  orders: Array<{
    id: string  // uuid
    number: string
    title: string
    itemCount: integer  // -9007199254740991–9007199254740991
    createdAt: string
    currency: string
    totalGrossMinor: integer  // -9007199254740991–9007199254740991
    paidGrossMinor: integer  // -9007199254740991–9007199254740991
    state: "paid" | "due" | "overdue" | "processing" | "scheduled" | "refunded"
    installments: Array<{
      index: integer  // -9007199254740991–9007199254740991
      state: "paid" | "processing" | "due" | "overdue" | "scheduled" | "refunded" | "unavailable"
      grossMinor: integer  // -9007199254740991–9007199254740991
    }>
    nextDueGrossMinor: integer | null
  }>
  counts: {
    all: integer  // -9007199254740991–9007199254740991
    due: integer  // -9007199254740991–9007199254740991
    paid: integer  // -9007199254740991–9007199254740991
    refunded: integer  // -9007199254740991–9007199254740991
  }
  nextOffset: integer  // -9007199254740991–9007199254740991
  hasMore: boolean
}

orders.screen.get · One order (screen)

One order: lines, net, VAT and total, the payer (name and tax id of the brand's own billing account), the works it delivers and its payment plan, each installment with its share, what triggers it (the payment step, or the plan chosen on the quote), amount and state, and which one can be paid now. Paying runs works.payments.start on that step, or orders.installments.start on an order installment.

Field	Value
Kind	Read
HTTP method	`POST /api/v1/orders.screen.get`
MCP tool	`orders_screen_get`
Scope	`orders.read`
Minimum role	Billing
Human confirmation	No
Doors	API, MCP, Screens, Apps, Nödo
Status	Available

Input

{
  orderId: string  // uuid
}

Output

{
  order: {
    id: string  // uuid
    number: string
    title: string
    createdAt: string
    currency: string
    state: "paid" | "due" | "overdue" | "processing" | "scheduled" | "refunded"
    lines: Array<{
      title: string
      quantity: number
      netMinor: integer  // -9007199254740991–9007199254740991
    }>
    totals: {
      netMinor: integer  // -9007199254740991–9007199254740991
      taxMinor: integer  // -9007199254740991–9007199254740991
      grossMinor: integer  // -9007199254740991–9007199254740991
      withholdingMinor: integer  // -9007199254740991–9007199254740991
      paidGrossMinor: integer  // -9007199254740991–9007199254740991
      remainingGrossMinor: integer  // -9007199254740991–9007199254740991
    }
    payer: {
      name: string | null
      taxId: string | null
    }
    | null
    works: Array<{
      id: string  // uuid
      name: string
    }>
    installments: Array<{
      taskId: string | null
      workId: string | null
      installmentId: string | null
      moment: "on_accept" | "midway" | "on_delivery" | null
      index: integer  // -9007199254740991–9007199254740991
      kind: "partial" | "final" | "single"
      percentBps: integer | null
      label: string
      netMinor: integer  // -9007199254740991–9007199254740991
      taxMinor: integer  // -9007199254740991–9007199254740991
      withholdingMinor: integer  // -9007199254740991–9007199254740991
      grossMinor: integer  // -9007199254740991–9007199254740991
      state: "paid" | "processing" | "due" | "overdue" | "scheduled" | "refunded" | "unavailable"
      dueDate: string | null
      paidAt: string | null
      method: string | null
    }>
    nextDueTaskId: string | null
    nextDueInstallmentId: string | null
    nextDuePayment: {
      taskId: string  // uuid
      grossMinor: integer  // -9007199254740991–9007199254740991
      currency: string
    }
    | null
    hasInvoice: boolean
  }
  canPay: boolean
}

orders.installments.start · Pay an installment

Prepares the PaymentIntent of the due installment of an order (the amount always comes from the server) for the person to confirm with Stripe. Only whoever pays for the brand.

Field	Value
Kind	Write
HTTP method	`POST /api/v1/orders.installments.start`
MCP tool	`orders_installments_start`
Scope	`orders.write`
Minimum role	Billing
Human confirmation	No
Doors	Screens, Apps
Status	Available

Input

{
  installmentId: string  // uuid
}

Output

{
  installment: {
    id: string  // uuid
    orderId: string  // uuid
    position: integer  // -9007199254740991–9007199254740991
    status: string
    grossMinor: integer  // -9007199254740991–9007199254740991
    currency: string
  }
  clientSecret: string | null
  publishableKey: string
  sheet?: {
    publishableKey: string
    customerId: string | null
    customerSessionClientSecret: string | null
    merchantCountryCode: "ES"
    merchantDisplayName: string
    googlePayEnvironment: "test" | "production"
  }
  | null
}

orders.installments.confirm · Check an installment payment

After the person confirms in Stripe, re-reads the payment on the server and marks the installment paid or processing.

Field	Value
Kind	Write
HTTP method	`POST /api/v1/orders.installments.confirm`
MCP tool	`orders_installments_confirm`
Scope	`orders.write`
Minimum role	Billing
Human confirmation	No
Doors	Screens, Apps
Status	Available

Input

{
  installmentId: string  // uuid
}

Output

{
  id: string  // uuid
  orderId: string  // uuid
  position: integer  // -9007199254740991–9007199254740991
  status: string
  grossMinor: integer  // -9007199254740991–9007199254740991
  currency: string
}

orders.installments.request · Request an installment

Nömad team only: asks for the next installment of an order when the work reaches it (earlier ones must have been requested). The brand's payers are told the amount, the due date (7 days unless given) and get the button to pay it.

Field	Value
Kind	Write
HTTP method	`POST /api/v1/orders.installments.request`
MCP tool	`orders_installments_request`
Scope	`orders.write`
Minimum role	Billing
Human confirmation	No
Doors	API, Screens, Apps
Status	Available

Input

{
  installmentId: string  // uuid
  dueDate?: string | null
}

Output

{
  id: string  // uuid
  orderId: string  // uuid
  position: integer  // -9007199254740991–9007199254740991
  status: string
  grossMinor: integer  // -9007199254740991–9007199254740991
  currency: string
}

orders.list · List orders

orders.screen.list · Orders (screen)

orders.screen.get · One order (screen)

orders.installments.start · Pay an installment

orders.installments.confirm · Check an installment payment

orders.installments.request · Request an installment

In this section