List Invoices

Retrieve a list of all invoices that you have created. You can filter the list with query parameters.

Parameters

Request Header Parameters

Request Query Parameters

- customer
- ID of the customer. String starting with cus_.
- date
- Date that the invoice was created.
- due_date
- The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the days_until_due field. Format is in Unix time.
- ending_before
- The ID of the invoice created after the last invoice you want to retrieve.
- limit
- The maximum number of invoices to return. Range: 1-100.
  10
- starting_after
- The ID of the invoice created before the first invoice you want to retrieve.
- subscription
- ID of the subscription. String starting with sub_.

Response Parameters

- attempt_count
- Total number of attempts made to pay this invoice.
- attempted
- Indicates whether an attempt has been made to pay the invoice automatically.
- automatic_attempt_count
- Number of automatic attempts that Rapyd made to retry paying this invoice if it failed.
- billing
- Determines the method of billing at the end of the billing cycle. Set to pay_automatically - Rapyd generates a payment object, then attempts to pay it using the designated payment method.
- billing_reason
- The reason for billing. One of the following:
  - subscription_cycle - A new cycle for the subscription.
  - subscription_create - A new subscription has been created.
  - manual - Customer was billed manually.
  - upcoming - Customer has an upcoming billing invoice.
- created_at
- The time the invoice was created, in Unix time.
- currency
- Three-letter ISO 4217 currency code for the currency used in all fields that refer to a monetary amount.
- customer
- ID of the customer that pays this invoice. String starting with cus_.
- days_until_due
- Number of days the customer has for paying this invoice. Integer.
- description
- Description of the invoice.
- discount
- Describes the discount that applies to this invoice. The source of the discount is one of the following:
  - If the invoice is generated manually, the discount is taken from the Customer object.
  - If the invoice is generated automatically from a subscription, the discount is taken from the Subscription object if it is defined there. Otherwise, it is taken from the Customer object.
- discount_amount
- The amount of the discount that was applied to this invoice.
- due_date
- The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the days_until_due field. Relevant when billing is send_invoice. Format is in Unix time.
- id
- ID of the invoice. String starting with invoice_.
- lines
- The individual line items that make up the invoice. These items are added with Create Invoice or Update Invoice. For details o the fields in the 'invoice_item' object, see Create Invoice Item.
- metadata
- A JSON object defined by the client. See Metadata.
- next_payment_attempt
- The time when the next payment attempt will be made, in Unix time.
- number
- Invoice number, starting with the invoice_prefix specified in the Customer object.
- payment
- The 'payment' object that was generated for this invoice. For details of the fields in the 'payment' object, see Create Payment.
- payment_fields
- Additional payment_options.
- payment_method
- ID of the payment method for paying the invoice.
- payout
- Reserved.
- payout_fields
- Reserved.
- period_end
- Last date in the period covered by the invoice, in Unix time.
- period_start
- First date in the period covered by the invoice, in Unix time.
- statement_descriptor
- Description of the invoice for the customer's credit card statement. Limited to 22 characters.
- status
- An invoice moves through a series of statuses.
  - draft - Starting status for all invoices. The invoice can still be edited or deleted. The subscription's 'simultaneous_invoice' field determines when the status automatically moves to open. At any time, payment of the invoice via the 'Pay Invoice' method can move the invoice to another status.
  - deleted - An invoice can be deleted only when its status is draft. This action is usually done after an invoice is created due to an error.
  - open - The invoice has been finalized, and the system is now waiting for the payment to be completed by the customer. The invoice can no longer be edited.
  - paid - The paid status is used for invoices that are paid. Invoices are automatically marked as paid when payments are processed by Rapyd.
  - void - Voiding is similar to deleting an invoice, but keeps a record of when it was created, finalized, and voided. Invoices with a void status cannot be paid.
  - uncollectible - This invoice cannot be paid by the customer.
- subscription
- ID of the subscription that generates charges to this customer. String starting with sub_.
- subtotal
- Total of all line items before discount and before tax. Decimal.
- tax
- The amount of tax charged. Decimal. This is calculated asT = R x (S - D), where:
  - T is the tax.
  - R is the tax rate in tax_percent.
  - S is the subtotal.
  - D is the discount.
- tax_percent
- The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal, up to four decimal places. Range: 0-100
- total
- Total after discount and tax. Decimal.
- type
- The type of the subscription: payment

Code Samples

.NET

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/invoices?limit=3");
                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest(
      'GET', '/v1/invoices?limit=3'
    );

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

PHP

<?php
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', "/v1/invoices?limit=3");
    var_dump($object);
} catch(Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

result = make_request(method='get', path='/v1/invoices?limit=3')
pprint(result)

/v1/invoices

List Invoices

curl -X get 'https://sandboxapi.rapyd.net/v1/invoices?limit=2' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "6dc4caca-8720-4082-b0d7-bad67eba0915"
    },
    "data": [
        {
            "id": "invoice_6dad95c1d91a47b8c59728eaccdd8c1c",
            "attempt_count": 0,
            "billing": "pay_automatically",
            "billing_reason": "subscription_cycle",
            "created_at": 1761613560000,
            "currency": "USD",
            "customer": "cus_5bee14584a78638ba717e746be62ee01",
            "description": "",
            "discount": null,
            "due_date": 1764205560000,
            "days_until_due": 0,
            "metadata": {},
            "payment": null,
            "payout": null,
            "payment_fields": null,
            "period_end": 1762269042000,
            "period_start": 1761664242000,
            "lines": [
                {
                    "id": "il_cd7fc7874db4d422456ade7a2e242196",
                    "amount": 500,
                    "currency": "USD",
                    "description": "SEO",
                    "discountable": true,
                    "invoice_item": "",
                    "metadata": {},
                    "period": {
                        "start": 1761664242,
                        "end": 1762269042
                    },
                    "proration": false,
                    "quantity": 1,
                    "plan": {
                        "id": "plan_82f9aebe54be79ae567293bb29ffd5a2",
                        "aggregate_usage": "sum",
                        "amount": 500,
                        "billing_scheme": "per_unit",
                        "created_at": 1668940516,
                        "currency": "USD",
                        "interval": "week",
                        "interval_count": 1,
                        "metadata": {},
                        "nickname": "Weekly SEO Basic",
                        "tiers": [],
                        "tiers_mode": "",
                        "transform_usage": {
                            "divide_by": 1,
                            "round": "up"
                        },
                        "trial_period_days": 0,
                        "usage_type": "licensed",
                        "active": false
                    },
                    "subscription": "sub_b45547bd37ba2dc9094dcd7b62983550",
                    "subscription_item": "subi_8868f1d4101cf4798324b9733e4bc550",
                    "type": "subscription"
                }
            ],
            "statement_descriptor": "",
            "subscription": "sub_b45547bd37ba2dc9094dcd7b62983550",
            "discount_amount": 0,
            "subtotal": 500,
            "tax": 0,
            "tax_percent": 0,
            "total": 500,
            "status": "draft",
            "payout_fields": null,
            "type": "payment"
        },
        {
            "id": "invoice_9c742e321151e05b8ecde0bfa3f260ef",
            "attempt_count": 0,
            "billing": "pay_automatically",
            "billing_reason": "subscription_cycle",
            "created_at": 1761613512000,
            "currency": "USD",
            "customer": "cus_5bee14584a78638ba717e746be62ee01",
            "description": "",
            "discount": null,
            "due_date": 1764205512000,
            "days_until_due": 0,
            "metadata": {},
            "payment": null,
            "payout": null,
            "payment_fields": null,
            "period_end": 1762269088000,
            "period_start": 1761664288000,
            "lines": [
                {
                    "id": "il_29a11ef7080ce7d1c8a1ba4ceafc1162",
                    "amount": 500,
                    "currency": "USD",
                    "description": "SEO",
                    "discountable": true,
                    "invoice_item": "",
                    "metadata": {},
                    "period": {
                        "start": 1761664288,
                        "end": 1762269088
                    },
                    "proration": false,
                    "quantity": 1,
                    "plan": {
                        "id": "plan_82f9aebe54be79ae567293bb29ffd5a2",
                        "aggregate_usage": "sum",
                        "amount": 500,
                        "billing_scheme": "per_unit",
                        "created_at": 1668940516,
                        "currency": "USD",
                        "interval": "week",
                        "interval_count": 1,
                        "metadata": {},
                        "nickname": "Weekly SEO Basic",
                        "tiers": [],
                        "tiers_mode": "",
                        "transform_usage": {
                            "divide_by": 1,
                            "round": "up"
                        },
                        "trial_period_days": 0,
                        "usage_type": "licensed",
                        "active": false
                    },
                    "subscription": "sub_420d05fbf9880585aa0d3aab1d46b07c",
                    "subscription_item": "subi_5983b66e297926bbec29c26f1c7123da",
                    "type": "subscription"
                }
            ],
            "statement_descriptor": "",
            "subscription": "sub_420d05fbf9880585aa0d3aab1d46b07c",
            "discount_amount": 0,
            "subtotal": 500,
            "tax": 0,
            "tax_percent": 0,
            "total": 500,
            "status": "draft",
            "payout_fields": null,
            "type": "payment"
        }
    ]
}

List Invoices for Subscription

curl -X get 'https://sandboxapi.rapyd.net/v1/invoices?subscription=sub_b2db5191d9623a958697614d665a5be5&limit=2' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "69a92147-6517-4e4e-805d-44a6e6061f3b"
    },
    "data": [
        {
            "id": "invoice_777377c23b361c4a205878173454fe52",
            "attempt_count": 0,
            "billing": "pay_automatically",
            "billing_reason": "subscription_create",
            "created_at": 1761221728000,
            "currency": "USD",
            "customer": "cus_4e25112ac20e144ad073a614dc46934b",
            "description": "",
            "discount": null,
            "due_date": 1763813728000,
            "days_until_due": 0,
            "metadata": {},
            "payment": null,
            "payout": null,
            "payment_fields": null,
            "period_end": 1766492127000,
            "period_start": 1761221727000,
            "lines": [
                {
                    "id": "il_7cf482fa969103c20997b834d49baa40",
                    "amount": 60,
                    "currency": "USD",
                    "description": "SaaS Users",
                    "discountable": true,
                    "invoice_item": "",
                    "metadata": {},
                    "period": {
                        "start": 1761221727,
                        "end": 1766492127
                    },
                    "proration": false,
                    "quantity": 1,
                    "plan": {
                        "id": "plan_9338044c6ca654abd79da7319c40b7dc",
                        "aggregate_usage": "sum",
                        "amount": 0,
                        "billing_scheme": "tiered",
                        "created_at": 1761210135,
                        "currency": "USD",
                        "interval": "month",
                        "interval_count": 2,
                        "metadata": {},
                        "nickname": "SaaS Users",
                        "tiers": [
                            {
                                "amount": 35,
                                "up_to": 5,
                                "flat_amount": 25
                            },
                            {
                                "amount": 30,
                                "up_to": 10,
                                "flat_amount": 0
                            },
                            {
                                "amount": 25,
                                "up_to": 25,
                                "flat_amount": 0
                            },
                            {
                                "amount": 20,
                                "up_to": 100,
                                "flat_amount": 0
                            },
                            {
                                "amount": 15,
                                "up_to": 500,
                                "flat_amount": 0
                            },
                            {
                                "amount": 10,
                                "up_to": "inf",
                                "flat_amount": 0
                            }
                        ],
                        "tiers_mode": "volume",
                        "transform_usage": {
                            "divide_by": 1,
                            "round": "up"
                        },
                        "trial_period_days": 0,
                        "usage_type": "licensed",
                        "active": true
                    },
                    "subscription": "sub_b2db5191d9623a958697614d665a5be5",
                    "subscription_item": "subi_fd4d2d48578564f16c3c19d3e09612b9",
                    "type": "subscription"
                }
            ],
            "statement_descriptor": "",
            "subscription": "sub_b2db5191d9623a958697614d665a5be5",
            "discount_amount": 0,
            "subtotal": 60,
            "tax": 0,
            "tax_percent": 0,
            "total": 60,
            "status": "paid",
            "payout_fields": null,
            "type": "payment"
        }
    ]
}

In this section:

Documentation

List Invoices

Parameters

Request Header Parameters

Request Query Parameters

Response Parameters

Code Samples

Search results