List Invoice

see list of invoice

Note: your API key must have the "Invoices" permission.

The List Invoice endpoint provides a paginated list of invoices, including details such as amounts, statuses, and associated shop information. Use this endpoint to retrieve multiple invoices at once and filter or sort them based on various criteria like status, creation date, and currency.

GET https://api.payhubix.com/v1/invoices/

Request Header:

Name	Type	Description
X-Api-Key*	string	Your API key for authentication and authorization.

Request Params:

Name	Type	Description
page*	integer	Specifies the page number of the results.
per_page*	integer	Sets the number of invoices per page.
status	string	Filters invoices by their status.
created_at	string	Sorts results by creation date (e.g., asc or desc).
currency_symbol	string	Filters invoices by their Fiat symbol(e.g, USD, EUR).

Response

Name	Type	Description
page_count*	integer	Total number of pages for the current request.
page*	integer	Current page number.
previous_page*	integer	Previous page number.
next_page*	integer	Next page number.
index*	integer	The position of the invoice in the list.
link*	string	A unique identifier for the invoice.
status*	string	The current status of the invoice (Created, Pending, Paid,Canceled,Partially, PartiallyExpired,Expired).
transfer_fee_by*	string	Who is responsible for the transfer fee (e.g., "Customer").
service_fee_by*	string	Who is responsible for the service fee (e.g., "Customer").
currency_amount*	float	The total invoice amount in the specified currency.
remaining_currency_amount*	float	The remaining unpaid amount.
currency_symbol*	string	The symbol of the currency (e.g.,fiats, "USD").
order_id	string	The ID of the associated order (if available).
shop.name*	string	Name of the shop.
shop.website	string	The website of the shop (if provided).
shop.shop_id*	string	The unique identifier for the shop.
shop.transfer_fee_by*	string	Specifies whether the fee for the transaction is covered by the customer or the merchant.
shop.service_fee_by*	string	Specifies who will cover the service fee.
shop.logo_url	string	URL of the shop's logo (if provided).
invoice_url*	string	The URL of invoice.
created_at*	string	The timestamp when the invoice was created (in UTC).

Note: thecurrency_symbolfield should be IDs of Supported Fiat.

Node: The current status of the invoice. Possible values are: Created, Pending, Paid,Canceled,Partially, PartiallyExpired,Expired

An example of response:

200: OK

{
    "error": false,
    "number": 0,
    "message": {
        "page_count": 2,
        "page": 1,
        "previous_page": 0,
        "next_page": 2,
        "invoices": [
             {
                "index": 1,
                "link": "INV-LV7VXM1A",
                "status": "Created",
                "transfer_fee_by": "Customer",
                "service_fee_by": "Customer",
                "currency_amount": 10,
                "remaining_currency_amount": 10,
                "currency_symbol": "USD",
                "currency_sign": "$",
                "order_id": null,
                "shop": {
                    "name": "Amazon",
                    "website": "amazon.com",
                    "shop_id": "01941c5f-3f34-7d2e-8537-17256d559426",
                    "transfer_fee_by": "Customer",
                    "service_fee_by": "Customer",
                    "logo_url": null
                },
                "invoice_url": "https://pay.payhubix.com/pay/INV-LV7VXM1A",
                "created_at": "2025-01-05 17:47:59.919249 +0000 UTC"
            },
            {
                "index": 2,
                "link": "INV-1923HWC4",
                "status": "Expired",
                "transfer_fee_by": "Customer",
                "service_fee_by": "Customer",
                "currency_amount": 1,
                "remaining_currency_amount": 1,
                "currency_symbol": "USD",
                "currency_sign": "$",
                "order_id": "#12325425",
                "shop": null,
                "invoice_url": "https://pay.payhubix.com/pay/INV-1923HWC4",
                "created_at": "2025-01-04 15:56:25.463136 +0000 UTC"
            }
        ]
    }
}

401: Unauthorized

{
    "error": true,
    "number": 401,
    "message": "Unauthorized access to api"
}

403: Forbidden

{
    "error": true,
    "number": 403,
    "message": "You don't have permission to access this resource."
}

500: Something went wrong

{
    "error": true,
    "number": 500,
    "message": "Oops! Something went wrong on our end."
}

Example codes:

cURL

curl --location 'https://api.payhubix.com/v1/invoices/?per_page=2&page=1' \
--header 'X-Api-Key: YOUR_API_KEY'

Python

import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}

params = {
    'per_page': '2',
    'page': '1',
}

response = requests.get('https://api.payhubix.com/v1/invoices/', params=params, headers=headers)

Node.js

import axios from 'axios';

const response = await axios.get('https://api.payhubix.com/v1/invoices/', {
  params: {
    'per_page': '2',
    'page': '1'
  },
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://api.payhubix.com/v1/invoices/', [
    'query' => [
        'per_page' => '2',
        'page' => '1'
    ],
    'headers' => [
        'X-Api-Key' => 'YOUR_API_KEY'
    ]
]);

Golang

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	client := &http.Client{}
	req, err := http.NewRequest("GET", "https://api.payhubix.com/v1/invoices/?per_page=2&page=1", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", bodyText)
}

Note: Please make sure to replace YOUR_API_KEY in the code snippets with your actual merchant API key