Update Invoice

Change or modify an invoice.

You can modify the invoice when its status is draft.

This method triggers the Invoice Updated Webhook. This webhook contains the same information as the response.

Parameters

Request Path Parameters

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

Request Header Parameters

Request Body Parameters

- days_until_due
- Number of days the customer has for paying this invoice. Integer.
  30
- description
- Description of the 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.
- metadata
- A JSON object defined by the client. See Metadata.
- payment_fields
- Additional payment_options.
- statement_descriptor
- Description of the invoice for the customer's credit card statement. Limited to 22 characters.
- 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

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;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string invoiceId = "invoice_e722956a315d42c94e93ce49153e7029";

                var requestObj = new
                {
                    days_until_due = 40,
                    metadata = new
                    {
                        merchant_defined = "updated"

                    }
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/invoices/{invoiceId}", request);

                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 body = {
      days_until_due: 40
    };
    const result = await makeRequest(
      'POST',
      '/v1/invoices/invoice_e722956a315d42c94e93ce49153e7029',
      body
    );

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

PHP

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

$body = [
    "metadata" => array(
        "merchant_defined" => "updated"
    ),
    "days_until_due" => 40
];

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

Python

from pprint import pprint

from utilities import make_request

invoice = {
    "metadata": {
        "merchant_defined": "updated"
    },
    "days_until_due": 40
}
result = make_request(method='post', path='/v1/invoices/invoice_e722956a315d42c94e93ce49153e7029', body=invoice)
pprint(result)

/v1/invoices/:invoice

Update Invoice

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_20d154c968ea36429ec5bc688254d0b1' \
-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 '{
    "days_until_due": 40,
    "metadata": {
        "merchant_defined": "updated"
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "1f7f6289-4645-453c-8130-37d2b107ad75"
    },
    "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": "draft",
        "payout_fields": null,
        "type": "payment"
    }
}

Bad Request - Days Until Due Not Valid

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_0ae79d418ce7a51029d8fba31b6eec2c' \
-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 '{
    "days_until_due": 770
}'

{
    "status": {
        "error_code": "ERROR_DAYS_UNTIL_DUE_NOT_VALID",
        "status": "ERROR",
        "message": "The request tried to set or update the 'days_until_due' parameter in an invoice or subscription, but the value was not valid. The request was rejected. Corrective action: Set 'days_until_due' to a positive integer.",
        "response_code": "ERROR_DAYS_UNTIL_DUE_NOT_VALID",
        "operation_id": "e6a05b7b-4edb-4e93-a462-fda1aa3fa1ae"
    }
}

Bad Request - Due Date Not Valid

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_0ae79d418ce7a51029d8fba31b6eec2c' \
-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 '{
    "due_date": "2026-06-01"
}'

{
    "status": {
        "error_code": "INVALID_DUE_DATE",
        "status": "ERROR",
        "message": "The request tried to set or update the due date of an invoice, but the value was not valid. The request was rejected. Corrective action: Set the 'due_date' body parameter to a valid Unix timestamp in the future.",
        "response_code": "INVALID_DUE_DATE",
        "operation_id": "52e8c775-95ba-4e74-9ffc-da9d1d86b498"
    }
}

In this section:

Documentation