--- title: "Finalize Invoice" source_url: https://docs.rapyd.net/en/finalize-invoice.html lang: en --- # Finalize Invoice Finalize an invoice. Invoices are initially created with a **draft** status, and this is the only state in which an invoice can be finalized. When an invoice is ready to be paid, finalize it. This sets its status to **open**. Subscriptions automatically create draft invoices during each billing cycle, which are then automatically finalized. When an invoice is finalized, it can no longer be deleted and its final status can be one of the following: - **paid** - **uncollectible** - **void** An invoice can be finalized only one time. This method triggers the [Invoice Finalized Webhook](https://docs.rapyd.net/en/invoice-finalized-webhook.md "Invoice Finalized Webhook"). This webhook contains the same information as the response. The following asynchronous webhooks provide information about later changes to the invoice: - [Invoice Payment Failed Webhook](https://docs.rapyd.net/en/invoice-payment-failed-webhook.md "Invoice Payment Failed Webhook") - [Payment Failed Webhook](https://docs.rapyd.net/en/payment-failed-webhook.md "Payment Failed Webhook") > **Note:** > > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Invoice Errors](https://docs.rapyd.net/en/invoice-errors.md "Invoice Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - invoice - ID of the invoice you want to finalize. String starting with **invoice_**. ### 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**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - 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 - - 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](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. - - 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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/create-invoice.md "Create Invoice") or [Update Invoice](https://docs.rapyd.net/en/update-invoice.md "Update Invoice"). For details o the fields in the 'invoice_item' object, see [Create Invoice Item](https://docs.rapyd.net/en/create-invoice-item.md "Create Invoice Item"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - next_payment_attempt - The time when the next payment attempt will be made, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/create-payment.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - period_start - First date in the period covered by the invoice, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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 as**T = 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 - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string invoice = "invoice_1785fecf9748e66319ce0848e6501072"; string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/invoices/{invoice}/finalize"); 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( 'POST', '/v1/invoices/invoice_1785fecf9748e66319ce0848e6501072/finalize' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('post', "/v1/invoices/invoice_1785fecf9748e66319ce0848e6501072/finalize"); var_dump($object); } catch(Exception $e) { echo "Error => $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request result = make_request(method='post', path='/v1/invoices/invoice_1785fecf9748e66319ce0848e6501072/finalize') pprint(result) ``` - /v1/invoices/:invoice/finalize - Finalize Invoice - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_20d154c968ea36429ec5bc688254d0b1/finalize' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "d16c265c-208c-49a4-8ff2-8d210ecfa45a" }, "data": { "id": "invoice_20d154c968ea36429ec5bc688254d0b1", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "manual", "created_at": 1764744320, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1768200320, "days_until_due": 40, "metadata": { "merchant_defined": "updated" }, "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158", "payment": null, "payout": null, "payment_fields": null, "period_end": 0, "period_start": 0, "lines": [], "statement_descriptor": "", "subscription": "", "discount_amount": 0, "subtotal": 0, "tax": 0, "tax_percent": 0, "total": 0, "status": "paid", "payout_fields": null, "type": "payment" } } ``` - Bad Request - Status Not Draft - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_90be94b2416dfb41b7458ad551e62e06/finalize' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "ERROR_UPDATE_NOT_DRAFT_INVOICE", "status": "ERROR", "message": "The request tried to a update an invoice but the invoice is not draft. Can only update draft invoice. The request was rejected.", "response_code": "ERROR_UPDATE_NOT_DRAFT_INVOICE", "operation_id": "8ae4d029-b12b-45ab-b35c-527334cfb732" } } ``` - Bad Request - Invoice Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_90be94b2416dfb41b7458ad551e62e0/finalize' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "ERROR_GET_INVOICE", "status": "ERROR", "message": "The request tried to retrieve an invoice, but the invoice was not found. The request was rejected. Corrective action: Use a valid invoice ID.", "response_code": "ERROR_GET_INVOICE", "operation_id": "5b7c15d0-90c4-4a0f-90c1-03c4a34ff8bf" } } ```