List Agreements API

HTTP Request

GET /v5/bybitpay/agreement/list

Query agreement list under merchant with pagination and filtering support.

---

Request Parameters

Parameter	Type	Required	Description
merchant_id	string	Yes	Merchant ID
user_id	string	No	Platform user ID (filter by user)
agreement_type	string	No	Sign type: CYCLE / NON_CYCLE / SINGLE (query all if not provided)
status	string	No	Status filter: INIT / PENDING / SIGNED / SUSPENDED / UNSIGNED / EXPIRED / FAILED
scene_code	string	No	Scene code filter
start_time	string	No	Sign start time (ISO8601)
end_time	string	No	Sign end time (ISO8601)
page_no	int	No	Page number, default 1
page_size	int	No	Page size, default 20, max 100

---

Response Parameters

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.total	int	Total record count
result.page_no	int	Current page number
result.page_size	int	Page size
result.list	array	Agreement list
result.list[].agreement_no	string	Platform agreement number
result.list[].external_agreement_no	string	Merchant agreement number
result.list[].user_id	string	Platform user ID
result.list[].merchant_user_id	string	Merchant-side user ID
result.list[].agreement_type	string	Sign type
result.list[].scene_code	string	Scene code
result.list[].status	string	Agreement status
result.list[].sign_time	string	Sign time
result.list[].valid_time	string	Validity period

---

Request Examples

List All Active Agreements

GET /v5/bybitpay/agreement/list?merchant_id=M123456789&status=SIGNED&page_no=1&page_size=20 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

List Agreements for Specific User

GET /v5/bybitpay/agreement/list?merchant_id=M123456789&user_id=U_123456789&page_no=1&page_size=20 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

List Agreements by Scene and Time Range

GET /v5/bybitpay/agreement/list?merchant_id=M123456789&scene_code=SUBSCRIPTION&start_time=2026-01-01T00:00:00Z&end_time=2026-01-31T23:59:59Z&page_no=1&page_size=50 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

---

Response Example

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "total": 150,
    "page_no": 1,
    "page_size": 20,
    "list": [
      {
        "agreement_no": "AGR202601070001",
        "external_agreement_no": "MERCHANT_AGR_001",
        "user_id": "U_123456789",
        "merchant_user_id": "merchant_user_123",
        "agreement_type": "CYCLE",
        "scene_code": "SUBSCRIPTION",
        "status": "SIGNED",
        "sign_time": "2026-01-07T10:30:00Z",
        "valid_time": "2027-01-07T10:30:00Z"
      },
      {
        "agreement_no": "AGR202601060001",
        "external_agreement_no": "MERCHANT_AGR_002",
        "user_id": "U_987654321",
        "merchant_user_id": "merchant_user_456",
        "agreement_type": "CYCLE",
        "scene_code": "TAXI",
        "status": "SIGNED",
        "sign_time": "2026-01-06T15:20:00Z",
        "valid_time": "2027-01-06T15:20:00Z"
      }
    ]
  }
}

---

Notes

• Use pagination for large result sets to avoid timeout
• Combine filters for efficient querying
• sign_time is used for time range filtering