--- agentTools: projectIndex: https://developer.flutterwave.com/llms.txt --- # Get bill payments history This document shows you how to retrieve a history of all purchased bill services including commission earned # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Flutterwave v3", "version": "3.0.0" }, "servers": [ { "url": "https://api.flutterwave.com/v3" } ], "security": [ {} ], "paths": { "/bills/history": { "get": { "summary": "Get bill payments history", "description": "This document shows you how to retrieve a history of all purchased bill services including commission earned", "operationId": "get-bill-payments-history", "parameters": [ { "name": "Authorization", "in": "header", "description": "Pass your secret key as a bearer token in the request header to authorize this call", "required": true, "schema": { "type": "string", "default": "Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X" } }, { "name": "status", "in": "query", "description": "The transaction status", "schema": { "type": "string", "enum": [ "Successful", "Failed", "Reversed" ], "default": "Successful" } }, { "name": "from", "in": "query", "description": "This is the start date it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD", "schema": { "type": "string", "default": "2018-08-01" } }, { "name": "to", "in": "query", "description": "This is the end date, it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD", "schema": { "type": "string", "default": "2018-08-27" } }, { "name": "page", "in": "query", "description": "The page index to start the search from.", "schema": { "type": "string", "default": "1" } }, { "name": "limit", "in": "query", "description": "The number of entries returned per page.", "schema": { "type": "string", "default": "10" } }, { "name": "reference", "in": "query", "description": "This unique identifier for a single payment.", "schema": { "type": "string", "default": "ref-abc123" } }, { "name": "batch_reference", "in": "query", "description": "This unique identifier for a bulk payment.", "schema": { "type": "string", "default": "batch-ref-abc123" } }, { "name": "category", "in": "query", "description": "The bill category code.", "schema": { "type": "string", "default": "CABLEBILLS" } }, { "name": "country", "in": "query", "description": "This is the country of the Biller.", "schema": { "type": "string", "enum": [ "NG", "GH", "KE", "ZM" ] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"status\": \"success\",\n \"message\": \"Bill history fetched successfully\",\n \"meta\": {\n \"page_info\": {\n \"total\": 4,\n \"total_pages\": 1,\n \"current_page\": 1\n }\n },\n \"data\": [\n {\n \"id\": 5494170,\n \"currency\": \"NGN\",\n \"customer_id\": \"0025401100\",\n \"frequency\": \"One Time\",\n \"amount\": \"200.00\",\n \"category\": \"Cable Bill Payment\",\n \"recurring_payment_id\": null,\n \"product\": \"DSTV Payment\",\n \"product_name\": \"DSTV Payment\",\n \"commission\": \"10.00\",\n \"transaction_date\": \"2024-03-08T16:40:00.547Z\",\n \"tx_id\": 5494170,\n \"customer_reference\": \"b3a67b4e-6fae-46b8-bfc4-9003e0939e8e\",\n \"country\": \"NG\",\n \"flw_ref\": \"247846329168\",\n \"tx_ref\": \"CF-FLYAPI-20240308044000296166\",\n \"batch_id\": 3387852,\n \"extra\": null,\n \"product_details\": \"FLY-API-NG-DSTV Payment\",\n \"status\": \"Successful\"\n },\n {\n \"id\": 5494155,\n \"currency\": \"NGN\",\n \"customer_id\": \"07065657658\",\n \"frequency\": \"One Time\",\n \"amount\": \"13.00\",\n \"category\": \"Airtime\",\n \"recurring_payment_id\": null,\n \"product\": \"AIRTIME\",\n \"product_name\": null,\n \"commission\": \"0.00\",\n \"transaction_date\": \"2024-03-08T15:57:12.97Z\",\n \"tx_id\": 5494155,\n \"customer_reference\": \"be3c7984-fe0c-4cb7-81c2-d3734f1dbd48\",\n \"country\": \"NG\",\n \"flw_ref\": \"BPUSSD1709913436071081\",\n \"tx_ref\": \"CF-FLYAPI-20240308035712257603\",\n \"batch_id\": 3387837,\n \"extra\": null,\n \"product_details\": \"FLY-API-NG-AIRTIME\",\n \"status\": \"Successful\"\n },\n {\n \"id\": 5494154,\n \"currency\": \"NGN\",\n \"customer_id\": \"07065657658\",\n \"frequency\": \"One Time\",\n \"amount\": \"11.00\",\n \"category\": \"Airtime\",\n \"recurring_payment_id\": null,\n \"product\": \"AIRTIME\",\n \"product_name\": null,\n \"commission\": \"0.00\",\n \"transaction_date\": \"2024-03-08T15:55:16.963Z\",\n \"tx_id\": 5494154,\n \"customer_reference\": \"d7a004b1-a581-4cd9-89ae-a1ff89c45c9a\",\n \"country\": \"NG\",\n \"flw_ref\": \"BPUSSD1709913319189093\",\n \"tx_ref\": \"CF-FLYAPI-20240308035516465263\",\n \"batch_id\": 3387836,\n \"extra\": null,\n \"product_details\": \"FLY-API-NG-AIRTIME\",\n \"status\": \"Successful\"\n },\n {\n \"id\": 5469189,\n \"currency\": \"NGN\",\n \"customer_id\": \"07065657658\",\n \"frequency\": \"One Time\",\n \"amount\": \"13.00\",\n \"category\": \"Airtime\",\n \"recurring_payment_id\": null,\n \"product\": \"AIRTIME\",\n \"product_name\": null,\n \"commission\": \"0.00\",\n \"transaction_date\": \"2024-03-01T14:41:02.493Z\",\n \"tx_id\": 5469189,\n \"customer_reference\": \"7fc8279d-e04f-409d-841a-bfd5279d4970\",\n \"country\": \"NG\",\n \"flw_ref\": \"BPUSSD1709304064772808\",\n \"tx_ref\": \"CF-FLYAPI-20240301024102687583\",\n \"batch_id\": 3361900,\n \"extra\": null,\n \"product_details\": \"FLY-API-NG-AIRTIME\",\n \"status\": \"Successful\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Bill history fetched successfully" }, "meta": { "type": "object", "properties": { "page_info": { "type": "object", "properties": { "total": { "type": "integer", "example": 4, "default": 0 }, "total_pages": { "type": "integer", "example": 1, "default": 0 }, "current_page": { "type": "integer", "example": 1, "default": 0 } } } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 5494170, "default": 0 }, "currency": { "type": "string", "example": "NGN" }, "customer_id": { "type": "string", "example": "0025401100" }, "frequency": { "type": "string", "example": "One Time" }, "amount": { "type": "string", "example": "200.00" }, "category": { "type": "string", "example": "Cable Bill Payment" }, "recurring_payment_id": {}, "product": { "type": "string", "example": "DSTV Payment" }, "product_name": { "type": "string", "example": "DSTV Payment" }, "commission": { "type": "string", "example": "10.00" }, "transaction_date": { "type": "string", "example": "2024-03-08T16:40:00.547Z" }, "tx_id": { "type": "integer", "example": 5494170, "default": 0 }, "customer_reference": { "type": "string", "example": "b3a67b4e-6fae-46b8-bfc4-9003e0939e8e" }, "country": { "type": "string", "example": "NG" }, "flw_ref": { "type": "string", "example": "247846329168" }, "tx_ref": { "type": "string", "example": "CF-FLYAPI-20240308044000296166" }, "batch_id": { "type": "integer", "example": 3387852, "default": 0 }, "extra": {}, "product_details": { "type": "string", "example": "FLY-API-NG-DSTV Payment" }, "status": { "type": "string", "example": "Successful" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } } }, "x-readme": { "headers": [ { "key": "Content-Type", "value": "application/json" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true, "_id": "5e36e596fe0cf5005142f849:673c6ecaeb51a1003697d5e6" } ```