Skip to main content

Query repayment requests

note

The order id, the repayment number and the dates in these examples are placeholders — get the ids from orders and repaymentRequests and replace the dates with your own.

Use repaymentRequests query to retrieve a paginated list of repayment requests (see Pagination). The filter argument accepts a RepaymentRequestComplexFilterInput object; how conditions are written and combined is described in Filtering.

Filter by status and update date​

Use status to build a work queue on the lifecycle of the return, for example the repayment requests in waiting_warehouse_reception, and updatedAt to pick up only what changed since your last poll. The returnedLines read in the same query are what you need to record the reception.

Request
query repaymentRequestsWaitingForWarehouse {
  repaymentRequests(
    first: 20
    filter: {
      and: [
        { fields: { status: { equals: waiting_warehouse_reception } } }
        { fields: { updatedAt: { greaterThanOrEqualsTo: "2026-02-01T00:00:00.000Z" } } }
      ]
    }
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      id
      number
      status
      updatedAt
      order {
        id
        number
      }
      shipping {
        status
        trackingNumber
      }
      returnedLines {
        id
        sku
        quantityExpected
      }
    }
  }
}
Response
{
  "data": {
    "repaymentRequests": {
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "WzE2Mzhd"
      },
      "nodes": [
        {
          "id": "567",
          "number": "RR-2026-0001",
          "status": "waiting_warehouse_reception",
          "updatedAt": "2026-02-14T10:00:00.000Z",
          "order": {
            "id": "12345",
            "number": "56089"
          },
          "shipping": {
            "status": "in_transit",
            "trackingNumber": "1Z999AA10123456784"
          },
          "returnedLines": [
            {
              "id": "98765",
              "sku": "SKU-1",
              "quantityExpected": 2
            }
          ]
        },
        {
          "id": "568",
          "number": "RR-2026-0002",
          "status": "waiting_warehouse_reception",
          "updatedAt": "2026-02-15T08:30:00.000Z",
          "order": {
            "id": "12346",
            "number": "56090"
          },
          "shipping": null,
          "returnedLines": [
            {
              "id": "98766",
              "sku": "SKU-2",
              "quantityExpected": 1
            }
          ]
        }
      ]
    }
  },
  "extensions": {
    "queryComplexity": 285,
    "bucketBalance": 9715,
    "bucketRestoreRate": 100
  }
}

The return shipping can be null (and its status is null until the carrier reports the first tracking): use the repayment request status to decide what to work on.

Get repayment requests from an order​

Use order with nested repaymentRequests to get all the repayment requests of an order (there can be more than one). Alternatively, filter repaymentRequests on order, for example filter: { fields: { order: { fields: { id: { equals: "12345" } } } } }.

Request
query repaymentRequestsForOrder {
  order(id: "12345") {
    id
    number
    repaymentRequests {
      id
      number
      status
    }
  }
}
Response
{
  "data": {
    "order": {
      "id": "12345",
      "number": "56089",
      "repaymentRequests": [
        {
          "id": "567",
          "number": "RR-2026-0001",
          "status": "waiting_warehouse_reception"
        }
      ]
    }
  },
  "extensions": {
    "queryComplexity": 7,
    "bucketBalance": 9993,
    "bucketRestoreRate": 100
  }
}

Filter by request number​

Use number to find a repayment request by its number.

Request
query repaymentRequestsByNumber {
  repaymentRequests(
    first: 20
    filter: {
      fields: {
        number: {
          equals: "RR-2026-0001"
        }
      }
    }
  ) {
    nodes {
      id
      number
      status
      createdAt
      updatedAt
    }
  }
}
Response
{
  "data": {
    "repaymentRequests": {
      "nodes": [
        {
          "id": "567",
          "number": "RR-2026-0001",
          "status": "waiting_warehouse_reception",
          "createdAt": "2026-02-14T09:00:00.000Z",
          "updatedAt": "2026-02-14T10:00:00.000Z"
        }
      ]
    }
  },
  "extensions": {
    "queryComplexity": 102,
    "bucketBalance": 9898,
    "bucketRestoreRate": 100
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

  • order:query:order
  • order:read
  • repayment_request:query:repayment_requests
  • repayment_request:read
  • repayment_returned_line:read
  • repayment_shipping:read