--- title: "Create Invoice Item" source_url: https://docs.rapyd.net/en/create-invoice-item.html lang: en --- # 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](https://docs.rapyd.net/en/invoice-updated-webhook.md "Invoice Updated Webhook") ### Parameters ### 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). ### 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](https://docs.rapyd.net/en/metadata.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/metadata.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - start - The start of the time period. [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - plan - Describes the pricing structure for the invoice item. For details of the fields in the 'plan' object, see [Create Plan](https://docs.rapyd.net/en/create-plan.md "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 - ```csharp 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 - ```javascript const makeRequest = require('/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 /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 - ```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 for Invoice - ```curl 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' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "invoice": "invoice_e7a973caf0dd43e73707fe22767c268f", "amount": 1050, "currency": "USD" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "063799de-16a6-4e46-9e3c-3b2da001ec74" }, "data": { "id": "ii_9da6c1053ce299a5b926299cab19be7f", "amount": 1050, "customer": "cus_4e25112ac20e144ad073a614dc46934b", "date": 1763561441, "description": "", "discountable": true, "invoice": "invoice_e7a973caf0dd43e73707fe22767c268f", "metadata": {}, "period": { "start": 0, "end": 0 }, "plan": { "product": {}, "transform_usage": {} }, "proration": 0, "quantity": 1, "subscription": "", "unit_amount": 1050 } } ``` - Create Invoice Item for Subscription - ```curl 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' \ --data-raw '{ "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "subscription": "sub_4e6a0aff92659de2ad3be965d0633952", "amount": 1050 }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "6317c9c0-b2ae-418c-b4f1-c229a522db21" }, "data": { "id": "ii_710e2f4476828ed34a88ee8fcf77fee1", "amount": 1050, "customer": "cus_4e25112ac20e144ad073a614dc46934b", "date": 1763561727, "description": "", "discountable": true, "invoice": "", "metadata": {}, "period": { "start": 0, "end": 0 }, "plan": { "product": {}, "transform_usage": {} }, "proration": 0, "quantity": 1, "subscription": "sub_4e6a0aff92659de2ad3be965d0633952", "unit_amount": 1050 } } ```