Create Invoice

Create an invoice to add a one-time charge to a subscription.

After you create the invoice with this method, create invoice items and assign them to the invoice with Create Invoice Item

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

The following asynchronous webhook provides information about later changes to the Invoice object:

Note

Clients who have PCI clearance can use card payment methods for an invoice.
The code samples include successful requests (200) and bad requests (400).
- For error messages that appear due to bad requests (400), see:
  - General Errors
  - Invoice Errors
- For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.

Parameters

Request Header Parameters

Request Body Parameters

- 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.
- currency
- Three-letter ISO 4217 currency code for the currency used in all fields that refer to a monetary amount. Required when the subscription field is not provided. If subscription field is provided, then the currency defined in the subscription's plan is used.
- 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.
  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.
- payment_method
- ID of the payment method for paying the invoice. If not provided, then the payment method is taken from the subscription. If the payment method is not provided in the subscription, the payment method is the customer's default payment method.
- statement_descriptor
- Description of the invoice for the customer's credit card statement. Limited to 22 characters.
- subscription
- ID of the subscription that generates charges to this customer. String starting with sub_.
- 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
            {
                var requestObj = new
                {
                    customer = "cus_efd877ff7df0b0259f021792d0780185",
                    billing = "pay_automatically",
                    days_until_due = "",
                    description = "",
                    due_date = 0,
                    metadata = new
                    {
                        merchant_defined = true

                    },
                    statement_descriptor = "",
                    subscription = "",
                    tax_percent = "",
                    currency = "USD"
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/invoices", 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 = {
      customer: 'cus_efd877ff7df0b0259f021792d0780185',
      billing: 'pay_automatically',
      days_until_due: null,
      description: '',
      due_date: 0,
      metadata: {
        merchant_defined: true
      },
      statement_descriptor: '',
      subscription: '',
      tax_percent: '',
      currency: 'USD'
    };
    const result = await makeRequest('POST', '/v1/invoices', 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 = [
    "customer" => "cus_efd877ff7df0b0259f021792d0780185",
    "billing" => "pay_automatically",
    "days_until_due" => null,
    "description" => "",
    "due_date" => 0,
    "statement_descriptor" => "",
    "subscription" => "",
    "tax_percent" => "",
    "currency" => "USD"
];

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

Python

from pprint import pprint

from utilities import make_request

invoice = {
    "customer": "cus_efd877ff7df0b0259f021792d0780185",
    "billing": "pay_automatically",
    "description": "",
    "due_date": 0,
    "metadata": {
        "merchant_defined": True
    },
    "statement_descriptor": "",
    "subscription": "",
    "tax_percent": "",
    "currency": "USD"
}
result = make_request(method='post', path='/v1/invoices', body=invoice)
pprint(result)

/v1/invoices

Create Invoice

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices' \
-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 '{
    "customer": "cus_4e25112ac20e144ad073a614dc46934b",
    "billing": "pay_automatically",
    "currency": "USD"
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "733f53d5-6081-4a1a-8f00-57379af6a48b"
    },
    "data": {
        "id": "invoice_c48bd622ee2e6ad6dd3ae4dc035dd451",
        "attempt_count": 0,
        "billing": "pay_automatically",
        "billing_reason": "manual",
        "created_at": 1761645737,
        "currency": "USD",
        "customer": "cus_4e25112ac20e144ad073a614dc46934b",
        "description": "",
        "discount": null,
        "due_date": 1764237737,
        "days_until_due": 30,
        "metadata": {},
        "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 - Customer Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices' \
-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 '{
    "billing": "pay_automatically",
    "currency": "USD"
}'

{
    "status": {
        "error_code": "INVALID_CUSTOMER",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a valid customer ID, but the customer was not found. The request was rejected. Corrective action: Use the correct customer, or create a new customer.",
        "response_code": "INVALID_CUSTOMER",
        "operation_id": "ec6e1765-0d74-41d4-af2e-63e60f80b74d"
    }
}

Bad Request - Currency Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/invoices' \
-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 '{
    "customer": "cus_4e25112ac20e144ad073a614dc46934b",
    "billing": "pay_automatically"
}'

{
    "status": {
        "error_code": "INVALID_CUSTOMER",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a valid customer ID, but the customer was not found. The request was rejected. Corrective action: Use the correct customer, or create a new customer.",
        "response_code": "INVALID_CUSTOMER",
        "operation_id": "ec6e1765-0d74-41d4-af2e-63e60f80b74d"
    }
}

In this section:

Documentation