---
title: "Retrieve Forecast Agreements"
method: POST
path: "/gateway/forecastagreement.json"
tags: ["Telr Agreement APIs"]
---

# Retrieve Forecast Agreements

`POST /gateway/forecastagreement.json`

Retrieves active (RUNNING) agreements whose next payment attempt falls within the given date range. Maximum date range: 31 days. If Fromdate is in the past it is silently adjusted to today. Todate must not be in the past. A duplicate-request lock prevents concurrent requests for the same store and auth key.

## Request body

- object
  - `ForecastAgreement` object, required
    - `storeid` string, required — Your Store ID.
    - `authkey` string, required — Authentication key. Found in Merchant Admin → Integrations → Hosted Payment Page → Configuration → Authentication Key.
    - `Fromdate` string, date, required — Start date for forecasting. Format: YYYY-MM-DD. Adjusted to today if in the past.
    - `Todate` string, date, required — End date for forecasting. Format: YYYY-MM-DD. Must not be in the past. Range cannot exceed 31 days.

## Response `200`

Successful response with forecast agreements data or error information.

- union
  - object
    - `ForecastAgreementResponse` object
      - `Code` integer
      - `Status` string
      - `data` ForecastAgreementItem[]
        - `AgreementID` integer — Unique identifier for the agreement.
        - `StoreID` integer — Store ID.
        - `Description` string — Agreement cart description.
        - `Currency` string — ISO 4217 currency code.
        - `NextDueAmount` string — Next payment amount in major currency units (minor units ÷ 100).
        - `Name` string — Cardholder full name (title + forename + surname).
        - `Address1` string — Billing address line 1.
        - `Address2` string — Billing address line 2.
        - `City` string — Billing city.
        - `Email` string, email — Billing email address.
        - `Phone` string — Billing telephone number.
        - `NextDueDate` string, date — Date of the next scheduled payment attempt.
        - `ActPayDate` string, date — Actual scheduled payment date in store timezone.
        - `FirstRef` string — Transaction reference of the first payment for this agreement.
        - `CartId` string — Cart identifier from the first transaction.
        - `AuthCount` integer — Number of successful authorisations on this agreement.
        - `RetryCount` integer — Number of retry attempts made.
        - `PaymentType` string — Card scheme or payment type (e.g. Visa, Mastercard, SADAD, STC Bank).
        - `PaymentInfo` string — Masked card number or non-card payment reference.
        - `CardExp` string — Card expiry formatted as MM/YYYY (note: includes trailing space).
        - `LastTran` string — Transaction reference of the most recent transaction.
        - `LastTranDate` string, date — Date of the most recent transaction.
        - `LastTranStatus` string — Status of the most recent transaction: Authorised, Held, Voided, Error, Declined, or Cancelled.
        - `LastSuccessDate` string — Date of the last successful payment (YYYY-MM-DD), or N/A if none on record.
        - `DefaultCat` string — Days-overdue category: N=before due, A=0–31 days, B=32–90 days, C=>90 days.
  - ErrorResponse
    - `code` integer — Error code
    - `status` string — Request status
    - `reason` string — Error reason
    - `errors` string[]

---

[API](https://skmtc.dev/telr/apis/remote-json-api-1-0.md) · [All operations](https://skmtc.dev/telr/apis/remote-json-api-1-0/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/telr/remote-json-api-1-0/revisions/7a1969c709ba/schema)