Orders & Payments

One-Time Orders

List Completed Orders

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { status: { eq: "completed" } }
    limit: 50
  ) {
    id
    buyerEmail
    currency
    priceSnapshot {
      currency
      subtotal
      taxAmount
      total
      taxCategory
    }
    status
    metadata
    createdAt
  }
  onetimeOrdersCount(storeId: $storeId)
}

Variables:

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }

Filter by Date Range

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: {
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

Look Up One-Time Order by Your Business Number (`orderMerchantExternalId`)

Pass the same orderMerchantExternalId you attached at checkout creation.

query($storeId: String!, $ref: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    orderMerchantExternalId
    createdAt
  }
}

Variables:

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "ORDER-2026-00891" }

SDK Example

const result = await client.graphql.query<{
  onetimeOrders: Array<{
    id: string;
    buyerEmail: string;
    priceSnapshot: { total: number; currency: string };
    status: string;
  }>;
}>({
  query: `query($storeId: String!) {
    onetimeOrders(storeId: $storeId, filter: { status: { eq: "completed" } }) {
      id buyerEmail priceSnapshot { total currency } status
    }
  }`,
  variables: { storeId: "STO_3bVzrkD0FJjFdZNLk8Ualx" },
});

Subscription Orders

List Active Subscriptions

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { in: ["active"] } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    createdAt
  }
  subscriptionOrdersCount(storeId: $storeId)
}

Filter Canceling Subscriptions

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { eq: "canceling" } }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

Look Up Subscription Order by Your Business Number (`orderMerchantExternalId`)

Pass the same orderMerchantExternalId you attached at checkout creation. Every renewal payment that follows inherits the same value, so a single business reference resolves the whole subscription lifecycle.

query($storeId: String!, $ref: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    orderMerchantExternalId
    createdAt
  }
}

Variables:

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "SUB-2026-01045" }

Which Billing Period a Subscription Is In

The billing period this subscription is in right now, as reported by the payment channel and stored unchanged — Waffo never computes or infers it. 1 during the first period, N during the Nth. 0 means the channel authorized the subscription but has not charged it yet. A failed charge still advances it, so it is not a count of successful charges. Null until the first channel notification arrives, and on subscriptions created before this field shipped. Same concept as the webhook data.periodNumber and Payment.periodNumber, read at a different anchor — see the field reference. This one moves as the subscription renews; Payment.periodNumber is frozen to the charge it belongs to.

query($storeId: String!) {
  subscriptionOrders(storeId: $storeId, filter: { status: { in: ["active"] } }) {
    id
    orderMerchantExternalId
    currentPeriodStart
    currentPeriodEnd
    currentPeriodNumber
  }
}

Payments

List Successful Payments

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    limit: 100
  ) {
    id
    orderId
    status
    refundStatus
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
  paymentsCount(filter: { status: { eq: "succeeded" } })
}

Filter by Date Range

query {
  payments(
    filter: {
      status: { eq: "succeeded" }
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    orderId
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
}

Look Up Payment by Waffo Payment ID

query($paymentId: String!) {
  payment(id: $paymentId) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    snapshotAmountDetails { total currency }
  }
}

Variables:

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

Look Up Payment by Your Business Number (`orderMerchantExternalId`)

Pass the same orderMerchantExternalId you attached at checkout creation. Field name mirrors webhook payload data.orderMerchantExternalId.

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    createdAt
  }
}

Variables:

{ "ref": "ORDER-2026-00891" }

For subscription orders, every renewal payment inherits the same orderMerchantExternalId set at checkout. The query above returns the full payment history for the same business reference, ordered by createdAt DESC.

Which Billing Period a Charge Paid For

periodNumber is the period that charge belongs to — 1 for the first charge, N for the Nth renewal — the same value the subscription payment webhook carried for it. A failed charge still consumes a period, so this is not a count of successful charges. Null on one-time payments and on payments created before this field shipped. It is frozen to its charge: a subscription now in period 3 still has periodNumber: 1 on its first payment. Use SubscriptionOrder.currentPeriodNumber when you want where the subscription is today.

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    periodNumber
    createdAt
  }
}

Variables:

{ "ref": "SUB-2026-01045" }

Aggregations & Sorting

Aggregate Payments by Day

paymentsAggregate returns count plus amount metrics (sum, avg, min, max) over all matching rows, optionally grouped by up to 2 dimensions. Available dimensions: status, currency, payment_method_type, card_brand, store, and the time dimension created_period. granularity (day, week, month, quarter, year; default day) only applies to the time dimension.

query {
  paymentsAggregate(
    filter: { status: { eq: "succeeded" }, currency: { eq: "USD" } }
    groupBy: [created_period]
    granularity: day
  ) {
    count
    amount { sum avg min max }
    groups {
      keys { dimension value }
      count
      amount { sum }
    }
    isTruncated
  }
}

Aggregate amount values are integer strings in minor currency units (e.g. cents). Amounts are summed across whatever rows match the filter, so group or filter by currency when multiple currencies are involved. Groups are sorted by count descending and capped at 100 (isTruncated flags truncation); the top-level count/amount always cover all matching rows. Other entities expose the same shape: refundsAggregate, onetimeOrdersAggregate, subscriptionOrdersAggregate, payoutTicketsAggregate, settlementBatchesAggregate, webhookDeliveriesAggregate, emailDeliveriesAggregate.

Sort with `orderBy`

List queries that support sorting accept orderBy: [XxxOrderBy!] (an enum whitelist), defaulting to created_at DESC. For payments the options are created_at_desc, created_at_asc, amount_desc, amount_asc.

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    orderBy: [amount_desc]
    limit: 20
  ) {
    id
    status
    snapshotAmountDetails { total currency }
    createdAt
  }
}

Refunds (executed records)

Refund records (order.refunds) are written after the PSP confirms the refund. They are separate from refund tickets — tickets carry the request lifecycle, refund records carry the executed result.

Look Up Refund by Waffo Refund ID

Refund exposes both business numbers as flat fields (orderMerchantExternalId from the originating order, refundTicketMerchantExternalId from the originating refund ticket) — same naming as the webhook payload.

query($refundId: String!) {
  refund(id: $refundId) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

Variables:

{ "refundId": "RFD_8aHbCcDdEeFfGgHhIiJjKk" }

Refund carries two amounts. amount is a Money object in minor currency units ("4900" for USD 49.00, with display giving "49.00"), while pspAmountDetails.amount is the amount the payment channel actually returned to the buyer, already as a display string ("49.00"). Reconcile against your channel statement with pspAmountDetails; isAmountMismatch is true when the requested and channel amounts differ.

Look Up Refunds by Payment (Waffo Payment ID)

query($paymentId: String!) {
  refunds(filter: { paymentId: { eq: $paymentId } }) {
    id
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

Look Up Refunds by Your Business Number

Match by the refund ticket’s business reference (what you attached when creating the refund ticket) — use the refundTicketMerchantExternalId filter:

query($ref: String!) {
  refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

Or match by the order’s business reference (returns all refunds against any payment carrying that reference, useful for subscription renewals) — filter at the payment layer and read its nested refunds:

query($paymentRef: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $paymentRef } }) {
    id
    orderMerchantExternalId
    refunds {
      id
      status
      refundTicketMerchantExternalId
      pspAmountDetails { amount currency }
      createdAt
    }
  }
}

Refund Tickets

List All Refund Tickets

query {
  refundTickets {
    id
    paymentId
    status
    requestedAmount
    reason
    createdAt
  }
  refundTicketsCount
}

Filter Pending Refunds

query {
  refundTickets(filter: { status: { eq: "pending" } }) {
    id
    paymentId
    requestedAmount
    reason
    createdAt
  }
}

Refunds for a Specific Payment

query($paymentId: String!) {
  refundTickets(filter: { subjectId: { eq: $paymentId } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    createdAt
  }
}

Variables:

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

Look Up Refund Tickets by Your Business Number (`refundTicketMerchantExternalId`)

query($ref: String!) {
  refundTickets(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    reviewNote
    rejectReason
    executedAt
    createdAt
  }
}

Variables:

{ "ref": "REF-2026-00891" }

RefundTicket (the request) and Refund (the executed record) are two different GraphQL types, but their business-side identifiers share the same flat names as the webhook payload: refundTicketMerchantExternalId on both RefundTicket and Refund; orderMerchantExternalId is additionally exposed on Refund (inherited from the originating order). Webhook payloads carry the same two values as data.orderMerchantExternalId and data.refundTicketMerchantExternalId.

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

One-Time Orders

List Completed Orders

Filter by Date Range

Look Up One-Time Order by Your Business Number (`orderMerchantExternalId`)

SDK Example

Subscription Orders

List Active Subscriptions

Filter Canceling Subscriptions

Look Up Subscription Order by Your Business Number (`orderMerchantExternalId`)

Which Billing Period a Subscription Is In

Payments

List Successful Payments

Filter by Date Range

Look Up Payment by Waffo Payment ID

Look Up Payment by Your Business Number (`orderMerchantExternalId`)

Which Billing Period a Charge Paid For

Aggregations & Sorting

Aggregate Payments by Day

Sort with `orderBy`

Refunds (executed records)

Look Up Refund by Waffo Refund ID

Look Up Refunds by Payment (Waffo Payment ID)

Look Up Refunds by Your Business Number

Refund Tickets

List All Refund Tickets

Filter Pending Refunds

Refunds for a Specific Payment

Look Up Refund Tickets by Your Business Number (`refundTicketMerchantExternalId`)

​One-Time Orders

​List Completed Orders

​Filter by Date Range

​Look Up One-Time Order by Your Business Number (orderMerchantExternalId)

​SDK Example

​Subscription Orders

​List Active Subscriptions

​Filter Canceling Subscriptions

​Look Up Subscription Order by Your Business Number (orderMerchantExternalId)

​Which Billing Period a Subscription Is In

​Payments

​List Successful Payments

​Filter by Date Range

​Look Up Payment by Waffo Payment ID

​Look Up Payment by Your Business Number (orderMerchantExternalId)

​Which Billing Period a Charge Paid For

​Aggregations & Sorting

​Aggregate Payments by Day

​Sort with orderBy

​Refunds (executed records)

​Look Up Refund by Waffo Refund ID

​Look Up Refunds by Payment (Waffo Payment ID)

​Look Up Refunds by Your Business Number

​Refund Tickets

​List All Refund Tickets

​Filter Pending Refunds

​Refunds for a Specific Payment

​Look Up Refund Tickets by Your Business Number (refundTicketMerchantExternalId)

One-Time Orders

List Completed Orders

Filter by Date Range

Look Up One-Time Order by Your Business Number (`orderMerchantExternalId`)

SDK Example

Subscription Orders

List Active Subscriptions

Filter Canceling Subscriptions

Look Up Subscription Order by Your Business Number (`orderMerchantExternalId`)

Which Billing Period a Subscription Is In

Payments

List Successful Payments

Filter by Date Range

Look Up Payment by Waffo Payment ID

Look Up Payment by Your Business Number (`orderMerchantExternalId`)

Which Billing Period a Charge Paid For

Aggregations & Sorting

Aggregate Payments by Day

Sort with `orderBy`

Refunds (executed records)

Look Up Refund by Waffo Refund ID

Look Up Refunds by Payment (Waffo Payment ID)

Look Up Refunds by Your Business Number

Refund Tickets

List All Refund Tickets

Filter Pending Refunds

Refunds for a Specific Payment

Look Up Refund Tickets by Your Business Number (`refundTicketMerchantExternalId`)