Create Invoice Item

Create an invoice item and add it to an invoice or subscription.

Note

If you create an invoice item without specifying the invoice ID or subscription ID, it is attached to the customer’s next invoice that has the same currency.

This method triggers the following webhooks:

Invoice Item Created - This webhook contains the same information as the response.
Invoice Updated Webhook

Parameters

Request Header Parameters

Request Body Parameters

- amount
- The amount of the total charge or credit for this item. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
  This is quantity times unit_amount. A credit is indicated by a negative number.
- currency
- Three-letter ISO 4217 code for the currency used in the amount field.
- customer
- ID of the customer. String starting with cus_.
- description
- Description of the invoice item.
- discountable
- Determines whether this invoice item is subject to the discount defined in the coupon that is assigned to the customer or subscription.
  For negative amounts and prorations, the default is false, and for all other invoice items, the default is true.
- invoice
- ID of the invoice that this invoice item is assigned to. Relevant when subscription is not set.
- metadata
- A JSON object defined by the client. See Metadata.
- quantity
- Indicates the number of units charged as a single invoice item. Integer.
- subscription
- ID of the subscription to assign this invoice item to. By default, the invoice item is assigned to the customer's subscription whose current billing cycle ends first. Relevant when invoice is not set.
- unit_amount
- Per-unit price of the product or service, adjusted as defined in the plan. Decimal.

Response Parameters

- amount
- The amount of the total charge or credit for this item. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
  This is quantity times unit_amount. A credit is indicated by a negative number.
- currency
- Three-letter ISO 4217 code for the currency used in the amount field.
- customer
- ID of the customer. String starting with cus_.
- date
- The time of the charge or credit, in Unix time.
- description
- Description of the invoice item.
- discountable
- Determines whether this invoice item is subject to the discount defined in the coupon that is assigned to the customer or subscription.
- id
- ID of the invoice item. String starting with ii_.
- invoice
- ID of the invoice that this invoice item is assigned to. Relevant when subscription is not set.
- metadata
- A JSON object defined by the client. See Metadata.
- period
- Defines the start and end of the time period that this invoice item refers to. Relevant when the invoice item refers to more than one day. Contains the following fields:
  - end
    The end of the time period. Unix time.
  - start
    The start of the time period. Unix time.
- plan
- Describes the pricing structure for the invoice item. For details of the fields in the 'plan' object, see Create Plan.
- proration
- Indicates whether the invoice item is prorated.
- quantity
- Indicates the number of units charged as a single invoice item. Integer.
- subscription
- ID of the subscription this invoice item is assigned to. By default, the invoice item is assigned to the customer's subscription whose current billing cycle ends first. Relevant when invoice is not set.
- unit_amount
- Per-unit price of the product or service, adjusted as defined in the plan. Decimal.

Code Samples

.NET

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    currency = "USD",
                    customer = "cus_b3b8ad0174f4c415c663b35bcf542192",
                    metadata = new
                    {
                        merchant_defined = true
                    },
                    amount = 10
                };

                string request = JsonSerializer.Serialize(requestObj);
                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/invoice_items", 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 = {
      currency: 'USD',
      customer: 'cus_b3b8ad0174f4c415c663b35bcf542192',
      metadata: {
        merchant_defined: true
      },
      amount: 10
    };
    const result = await makeRequest('POST', '/v1/invoice_items', body);

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

PHP

<?php
$path .= "/<path-to-your-utility-file>/utilities.php";
$body = [
  "currency" => "USD"
  "customer" => "cus_b3b8ad0174f4c415c663b35bcf542192",
  "amount" => 10   
];

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

Python

from pprint import pprint

from utilities import make_request

invoice_item = {
    "currency": "USD",
    "customer": "cus_b3b8ad0174f4c415c663b35bcf542192",
    "metadata": {
        "merchant_defined": True
    },
    "amount": 10
}
result = make_request(method='post', path='/v1/invoice_items', body=invoice_item)
pprint(result)

/v1/invoice_items

Create Invoice Item

curl -X post
https://sandboxapi.rapyd.net/v1/invoice_items
-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'
-d '{
    "currency": "USD",
    "customer": "cus_b3b8ad0174f4c415c663b35bcf542192",
    "metadata": {
        "merchant_defined": true
    },
    "amount": 10
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a5b56755-2372-48f0-8edc-c352c46197bc"
    },
    "data": {
        "id": "ii_907b7394d7794b6eb5007a247c6b3d62",
        "amount": 10,
        "customer": "cus_b3b8ad0174f4c415c663b35bcf542192",
        "date": 1560933177,
        "description": "",
        "discountable": true,
        "invoice": "invoice_752f1d3b7e2924c82fc96648871346c5",
				"metadata": {
					  "merchant_defined": true
				},
        "period": {
            "start": 0,
            "end": 0
        },
        "plan": {
            "product": null,
            "transform_usage": {}
        },
        "proration": 0,
        "quantity": 0,
        "subscription": "",
        "unit_amount": 0
    }
}

Create Invoice Item for Invoice

curl -X post
https://sandboxapi.rapyd.net/v1/invoice_items
-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'
-d '{
    "currency": "USD",
    "customer": "cus_f7f610d30df3aca230d75cbe8ad18d52",
    "invoice":"invoice_752f1d3b7e2924c82fc96648871346c5",
    "metadata": {
        "merchant_defined": true
    },
    "amount": 10
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "d81cf11d-0dc9-4b50-a65d-5117cff6fd24"
    },
    "data": {
        "id": "ii_e23625f991141726c459808c5436f6c6",
        "amount": 10,
        "customer": "cus_f7f610d30df3aca230d75cbe8ad18d52",
        "date": 1604926978,
        "description": "",
        "discountable": true,
        "invoice": "invoice_752f1d3b7e2924c82fc96648871346c5",
        "metadata": {
            "merchant_defined": true
        },
        "period": {
            "start": 0,
            "end": 0
        },
        "plan": {
            "product": null,
            "transform_usage": {}
        },
        "proration": 0,
        "quantity": 1,
        "subscription": "",
        "unit_amount": 10
    }
}

Create Invoice Item for Subscription

curl -X post
https://sandboxapi.rapyd.net/v1/invoice_items
-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'
-d '{
    "currency": "USD",
    "customer": "cus_5bee14584a78638ba717e746be62ee01",
    "subscription": "sub_840c00bf5c86f250f15881c3add2ae5e",
    "metadata": {
        "merchant_defined": true
    },
    "amount": 15
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "516b00ec-9bb3-4609-9f9f-3a66349cd361"
    },
    "data": {
        "id": "ii_d6733ca7ee9845fb23dad902f25ab6c4",
        "amount": 15,
        "customer": "cus_5bee14584a78638ba717e746be62ee01",
        "date": 1675695499,
        "description": "",
        "discountable": true,
        "invoice": "",
        "metadata": {
            "merchant_defined": true
        },
        "period": {
            "start": 0,
            "end": 0
        },
        "plan": {
            "product": null,
            "transform_usage": {}
        },
        "proration": 0,
        "quantity": 1,
        "subscription": "sub_840c00bf5c86f250f15881c3add2ae5e",
        "unit_amount": 15
    }
}

In this section:

Documentation