--- title: "Retrieve Invoice Lines from Upcoming Invoice" source_url: https://docs.rapyd.net/en/retrieve-invoice-lines-from-upcoming-invoice.html lang: en --- # Retrieve Invoice Lines from Upcoming Invoice Retrieve invoice lines from the upcoming invoice for a customer. If a customer has more than one subscription, this method retrieves the invoice lines of the invoice that is due first. > **Note:** > > This method is relevant to invoices that are automatically generated out of subscriptions. ### Parameters ### Request Query Parameters - - customer - ID of the customer whose invoice you want to retrieve. - - currency - Three-letter ISO 4217 code for the currency. Required when the invoice is not linked to a specific subscription. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters Multiple objects with the following parameters: - - amount - The amount of the invoice line. - - created_at - The time the invoice was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - Three-letter ISO 4217 currency code for the currency used in all fields that refer to a monetary amount. - - description - Description of the invoice line. - - discountable - Indicates if the invoice line item is discountable. - - id - The ID of the invoice line. String starting with **il_**. - - invoice_item - When relevant, displays the related `invoice_item` ID. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - payment_method - ID of the payment method for paying the invoice. - - period - The billing period. - - period_start - First date in the period covered by the invoice line, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - period_end - Last date in the period covered by the invoice line, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - proration - Indicates if proration is used for this invoice line. - - plan - The plan that is linked to the invoice line. - - active - Indicates whether the plan is available to be added to a subscription. - - aggregate_usage - Determines which quantity is used to calculate the pricing. One of the following: - **max** - The maximum reported usage within the billing cycle. - **sum** - The sum of all usage during a billing cycle. - **last_during_period** - The last usage reported within the billing cycle. - **last_ever** - The last usage ever reported, if the latest billing cycles contain no usage at all. - - amount - The amount to charge, in units of the currency defined in `currency`. Relevant when `billing_scheme` is set to **per_unit**. - - billing_scheme - Describes how to compute the price. One of the following: - **per_unit** - The amount specified in `amount` is charged for each unit. - **tiered** - The unit pricing is computed using a tiering strategy as defined with the `tiers` and `tiers_mode` fields. - - created_at - Time the `plan` object was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - Three-letter ISO 4217 code for the currency used in fields that represent monetary amounts. - - id - Unique ID for this plan. - - interval - Specifies the units used in defining the billing cycle. One of the following: - **day** - **week** - **month** - **year** - - interval_count - Number of time intervals in the billing cycle. Integer. See `interval`. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - nickname - Brief description of the plan. - - tiers - Defines a tiered pricing structure. Each tier object represents a pricing tier. Relevant when `billing_scheme` is set to **tiered**. Contains the following fields: - `amount` - The price for each item in this tier. Decimal number. - `up_to` - The upper volume limit for this tier. Valid values: **inf** (infinite) or an integer. - `flat_amount` - Extra amount added to the entire tier. Default is 0. - - tiers_mode - Determines the mode for calculating the total tiered charge. One of the following values: - **graduated** - The total cost at each price tier is calculated separately, then all tier charges are added together. - **volume** - The total cost is calculated as the number of service units multiplied by the applicable tier price. - - transform_usage - Defines the transformation that is applied to the reported usage before the billed price is computed. The transformation divides the quantity by the divisor specified in `divide_by`, then rounds up or down according to the setting in `round`. Relevant when `billing_scheme` is set to **per_unit**. Relevant when `billing_scheme` is set to **per_unit**. For more information, see **Transformation Pricing** in [Pricing Plans](https://docs.rapyd.net/en/plan-542850.md#UUID-1bf47980-9184-1c69-7a42-11128cd18cf6_UUID-7a4550ef-636e-1f11-6a3e-0c123f5455eb "Pricing Plans"). Contains the following fields: - - divide_by - Indicates the divisor in the transformation calculation. Integer. - - round - Indicates whether the reported number of units should be rounded **up** or **down** to the next whole quantity specified in `divide_by`. - - trial_period_days - The number of days in the customer's free trial period. Integer. Range: 0-730. - - usage_type - Determines whether the customer is billed when the service is not actually used. Relevant when `billing_scheme` is set to **per_unit**. One of the following: - **metered** - The customer is billed only for actual usage. - **licensed** - The customer is billed even if the service is not used. - - quantity - The quantity for the line item. - - subscription_item - The identifier of the subscription item object that is linked to this invoice line. String starting with **subi_**. - - subscription - ID of the subscription that generates charges to this customer. String starting with **sub_**. - - type - The type of the subscription: **payment** ### Code Samples - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string customer = "cus_478a0ffb8ad771c1bf9736e4b9e2b5f1"; string currency = "USD"; string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/invoices/upcoming/lines?customer={customer}¤cy={currency}"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest( 'GET', '/v1/invoices/upcoming/lines?customer=cus_478a0ffb8ad771c1bf9736e4b9e2b5f1¤cy=USD' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('get', "/v1/invoices/upcoming/cus_478a0ffb8ad771c1bf9736e4b9e2b5f1/lines?currency=USD"); var_dump($object); } catch(Exception $e) { echo "Error => $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request result = make_request(method='get', path='/v1/invoices/upcoming/lines?customer=cus_478a0ffb8ad771c1bf9736e4b9e2b5f1¤cy=USD') pprint(result) ``` - /v1/invoices/upcoming/lines - Retrieve Invoice Lines from Upcoming Invoice for Customer - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/invoices/upcoming/lines?customer=cus_478a0ffb8ad771c1bf9736e4b9e2b5f1' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "ea756adf-a399-45b6-8241-90484e988ed2" }, "data": [ { "id": "invoice_e7a973caf0dd43e73707fe22767c268f", "attempt_count": 1, "billing": "pay_automatically", "billing_reason": "manual", "created_at": 1763561380000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1766153380000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": null, "period_start": null, "lines": [ { "id": "il_e89ff184af1324212edbd583afca20f6", "amount": 19.99, "currency": "USD", "description": "Remaining time on Unlimited Music after 18 Nov 2025", "discountable": false, "invoice_item": "ii_35411466a031d8ae7f283fc9d0076f96", "metadata": {}, "period": { "start": 1763462590, "end": 1766054540 }, "proration": true, "quantity": 1, "plan": null, "subscription": "sub_423cac7708b84939baf3d4a55b153a19", "subscription_item": "", "type": "" }, { "id": "il_b3c6cf1fb232587229bdf5b8eab56d42", "amount": 9.99, "currency": "USD", "description": "Remaining time on Unlimited Music after 18 Nov 2025", "discountable": false, "invoice_item": "ii_d1fa6c9c886b42a100a511655839d2ea", "metadata": {}, "period": { "start": 1763455774, "end": 1766047667 }, "proration": true, "quantity": 1, "plan": null, "subscription": "sub_e38643c5d8d59f4ccd8ae08f8cc61c8d", "subscription_item": "", "type": "" }, { "id": "il_cb62056ca87c4dc5a4cf5252d48ee65e", "amount": 1050, "currency": "USD", "description": "", "discountable": true, "invoice_item": "ii_9da6c1053ce299a5b926299cab19be7f", "metadata": {}, "period": { "start": 0, "end": 0 }, "proration": false, "quantity": 1, "plan": null, "subscription": "", "subscription_item": "", "type": "" } ], "statement_descriptor": "", "subscription": "", "discount_amount": 0, "subtotal": 1079.98, "tax": 0, "tax_percent": 0, "total": 1079.98, "status": "open", "payout_fields": null, "type": "payment" }, { "id": "invoice_31973661cbf6dc7159a82a714d7aec20", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_create", "created_at": 1763462540000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1766054540000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1766054540000, "period_start": 1763462540000, "lines": [ { "id": "il_c37898704011f69416e40fe9c263fb0b", "amount": 9.99, "currency": "USD", "description": "Unlimited Music", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1763462540, "end": 1766054540 }, "proration": false, "quantity": 1, "plan": { "id": "plan_7d3521c7b8ddde8f7795c2341a5da819", "aggregate_usage": "sum", "amount": 9.99, "billing_scheme": "per_unit", "created_at": 1763462523, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "nickname": "Unlimited Plan", "tiers": [], "tiers_mode": "", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true }, "subscription": "sub_423cac7708b84939baf3d4a55b153a19", "subscription_item": "subi_79b1f3f3415ff2e12ec7f4762463ea03", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_423cac7708b84939baf3d4a55b153a19", "discount_amount": 0, "subtotal": 9.99, "tax": 0, "tax_percent": 0, "total": 9.99, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_1e692b6c43c9c94d20148ca96c033ccb", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_create", "created_at": 1763455668000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1766047668000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1766047667000, "period_start": 1763455667000, "lines": [ { "id": "il_ba3d2d1f2a070402a14d8d86f488663b", "amount": 5, "currency": "USD", "description": "Transit Rides", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1763455667, "end": 1766047667 }, "proration": false, "quantity": 1, "plan": { "id": "plan_390625a173f599153b5250715d861718", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1756282338, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "nickname": "Transit Use", "tiers": [ { "amount": 4, "up_to": 5, "flat_amount": 1 }, { "amount": 3, "up_to": 10, "flat_amount": 0 }, { "amount": 2, "up_to": 20, "flat_amount": 0 }, { "amount": 1, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "graduated", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true }, "subscription": "sub_e38643c5d8d59f4ccd8ae08f8cc61c8d", "subscription_item": "subi_7987dc3af04f7d0b6ba959e54bba24b7", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_e38643c5d8d59f4ccd8ae08f8cc61c8d", "discount_amount": 0, "subtotal": 5, "tax": 0, "tax_percent": 0, "total": 5, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_c8ec8695c381e318e27a3c2e480e4d17", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_create", "created_at": 1763039439000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1765631439000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1765631439000, "period_start": 1763039439000, "lines": [ { "id": "il_e55fa926e28c7b77de2d7204037a6931", "amount": 5, "currency": "USD", "description": "Transit Rides", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1763039439, "end": 1765631439 }, "proration": false, "quantity": 1, "plan": { "id": "plan_390625a173f599153b5250715d861718", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1756282338, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "nickname": "Transit Use", "tiers": [ { "amount": 4, "up_to": 5, "flat_amount": 1 }, { "amount": 3, "up_to": 10, "flat_amount": 0 }, { "amount": 2, "up_to": 20, "flat_amount": 0 }, { "amount": 1, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "graduated", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true }, "subscription": "sub_3d31e834b32be8bbbe9cc371f1cb6f58", "subscription_item": "subi_b4995f52ad0881e86605380cf68f036d", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_3d31e834b32be8bbbe9cc371f1cb6f58", "discount_amount": 0, "subtotal": 5, "tax": 0, "tax_percent": 0, "total": 5, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_ce2bdbcfc63543ba52f11da474ba89e0", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_create", "created_at": 1761820707000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1764412707000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1764499107000, "period_start": 1761820707000, "lines": [ { "id": "il_1e2f58639be722d4dbfc0ffe1fdce951", "amount": 5, "currency": "USD", "description": "Transit Rides", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1761820707, "end": 1764499107 }, "proration": false, "quantity": 1, "plan": { "id": "plan_390625a173f599153b5250715d861718", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1756282338, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "nickname": "Transit Use", "tiers": [ { "amount": 4, "up_to": 5, "flat_amount": 1 }, { "amount": 3, "up_to": 10, "flat_amount": 0 }, { "amount": 2, "up_to": 20, "flat_amount": 0 }, { "amount": 1, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "graduated", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true }, "subscription": "sub_4e6a0aff92659de2ad3be965d0633952", "subscription_item": "subi_58edb2b0362ab66791b988afaffa539e", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_4e6a0aff92659de2ad3be965d0633952", "discount_amount": 0, "subtotal": 5, "tax": 0, "tax_percent": 0, "total": 5, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_952b0717ba038a9e6bfadd9fdc81f723", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_cycle", "created_at": 1761820126000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1764412126000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1761820126000, "period_start": 1761226223000, "lines": [], "statement_descriptor": "", "subscription": "sub_d25185e18bd1509108cbc0b285a8243c", "discount_amount": 0, "subtotal": 0, "tax": 0, "tax_percent": 0, "total": 0, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_3e15686aa8a0bb294b5ec524b22386c5", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_cycle", "created_at": 1761820068000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1764412068000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1761820068000, "period_start": 1761221727000, "lines": [], "statement_descriptor": "", "subscription": "sub_b2db5191d9623a958697614d665a5be5", "discount_amount": 0, "subtotal": 0, "tax": 0, "tax_percent": 0, "total": 0, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_c48bd622ee2e6ad6dd3ae4dc035dd451", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "manual", "created_at": 1761645737000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1764237737000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": null, "period_start": null, "lines": [], "statement_descriptor": "", "subscription": "", "discount_amount": 0, "subtotal": 0, "tax": 0, "tax_percent": 0, "total": 0, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_325572ff1b407f2075e2cbb6ba7a25ea", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_cycle", "created_at": 1761526820000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1764118820000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1764234136000, "period_start": 1761555736000, "lines": [ { "id": "il_21412cea5f53c06007cd491aa4fbdb44", "amount": 5, "currency": "USD", "description": "Monthly parking", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1761555736, "end": 1764234136 }, "proration": false, "quantity": 1, "plan": { "id": "plan_1d3f0ee82ac33c3b4f37a193f1d3d797", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1756284134, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "nickname": "Transit Use", "tiers": [ { "amount": 4, "up_to": 5, "flat_amount": 1 }, { "amount": 3, "up_to": 10, "flat_amount": 0 }, { "amount": 2, "up_to": 20, "flat_amount": 0 }, { "amount": 1, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "graduated", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true }, "subscription": "sub_57c0891a5f34d8ff675018852dc15440", "subscription_item": "subi_1396bb97ba901905be2f04e62c1db038", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_57c0891a5f34d8ff675018852dc15440", "discount_amount": 0, "subtotal": 5, "tax": 0, "tax_percent": 0, "total": 5, "status": "paid", "payout_fields": null, "type": "payment" }, { "id": "invoice_4cbedc1fcb20e4a7f2387966676685a0", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "subscription_create", "created_at": 1761226224000, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1763818224000, "days_until_due": 0, "metadata": {}, "payment": null, "payout": null, "payment_fields": null, "period_end": 1766496623000, "period_start": 1761226223000, "lines": [ { "id": "il_d1d1f39ddd6f2d4897e0a92687c76530", "amount": 60, "currency": "USD", "description": "SaaS Users", "discountable": true, "invoice_item": "", "metadata": {}, "period": { "start": 1761226223, "end": 1766496623 }, "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_d25185e18bd1509108cbc0b285a8243c", "subscription_item": "subi_1bba618bdb03542772fd608e3e6fe2bf", "type": "subscription" } ], "statement_descriptor": "", "subscription": "sub_d25185e18bd1509108cbc0b285a8243c", "discount_amount": 0, "subtotal": 60, "tax": 0, "tax_percent": 0, "total": 60, "status": "paid", "payout_fields": null, "type": "payment" } ] } ```