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. This webhook contains the same information as the response.

The following asynchronous webhooks provide information about later changes to the invoice:

Parameters

Request Path Parameters

- invoice
- ID of the invoice you want to finalize. String starting with invoice_.

Request Header Parameters

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 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

const makeRequest = require('<path-to-your-utility-file>/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
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('post', "/v1/invoices/invoice_1785fecf9748e66319ce0848e6501072/finalize");
    var_dump($object);
} catch(Exception $e) {
    echo "Error => $e";
}
?>

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 -X post
https://sandboxapi.rapyd.net/v1/invoices/invoice_d021dc5aadaae5c810ed076a64065699/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'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "449e772d-b6a4-407e-9574-9e3e46a7d473"
    },
    "data": {
        "id": "invoice_d021dc5aadaae5c810ed076a64065699",
        "attempt_count": 1,
        "billing": "pay_automatically",
        "billing_reason": "subscription_create",
        "created_at": 1702305351,
        "currency": "USD",
        "customer": "cus_893a041b7dd251ec894556564298dc13",
        "description": "",
        "discount": null,
        "due_date": 1704897351,
        "days_until_due": 30,
        "metadata": {
            "merchant_defined": true
        },
            "failure_code": "",
            "failure_message": "",
            "paid": true,
            "paid_at": 1702305377,
            "dispute": null,
            "refunds": null,
            "order": null,
            "outcome": null,
            "visual_codes": {},
            "textual_codes": {},
            "instructions": [],
            "ewallet_id": "ewallet_8d09667ac2a0d4ba57d2765c497491fd",
            "ewallets": [
                {
                    "ewallet_id": "ewallet_8d09667ac2a0d4ba57d2765c497491fd",
                    "amount": 9.99,
                    "percent": 100,
                    "refunded_amount": 0
                }
            ],
            "payment_method_options": {},
            "payment_method_type": "at_visa_card",
            "payment_method_type_category": "card",
            "fx_rate": 1,
            "merchant_requested_currency": null,
            "merchant_requested_amount": null,
            "fixed_side": "",
            "payment_fees": null,
            "invoice": "invoice_d021dc5aadaae5c810ed076a64065699",
            "escrow": null,
            "group_payment": "",
            "cancel_reason": null,
            "initiation_type": "customer_present",
            "mid": "mid_f79561a67d79c6e0162bf22f3ccd1292",
            "next_action": "not_applicable",
            "error_code": "",
            "remitter_information": {}
        },
        "payout": null,
        "payment_fields": null,
        "period_end": 1704983751,
        "period_start": 1702305351,
        "lines": [],
        "statement_descriptor": "",
        "subscription": "sub_4febac6e4554b387ae7e0ee2d933abed",
        "discount_amount": 0,
        "subtotal": 9.99,
        "tax": 0,
        "tax_percent": 0,
        "total": 9.99,
        "status": "paid",
        "payout_fields": null,
        "type": "payment",
        "next_payment_attempt": 1702308951,
        "automatic_attempt_count": 0
    }
}

In this section:

Documentation