diff --git a/source/includes/_invoice.md b/source/includes/_invoice.md index 122e751..780b6ca 100644 --- a/source/includes/_invoice.md +++ b/source/includes/_invoice.md @@ -22,56 +22,62 @@ An invoice can have one of the following status values: DRAFT, COMMITTED, or VOI An `Invoice` resource represents an invoice associated with a specific account. The attributes contained in this resource are the following: -| Name | Type | Generated by | Description | -| ---- | -----| -------- | ------------ | -| **invoiceId** | string | system | UUID for the invoice | -| **accountId** | string | system | UUID for the account | -| **amount** | number | user or system | Sum of all item amounts | -| **currency** | string | user or system | Currency associated with the account | -| **status** | string | system | Status of the invoice: DRAFT, COMMITTED or VOID | -| **creditAdj** | number | system | Invoice credit (amount that we owe to the customer). It is calculated as the sum of `CBA_ADJ` invoice items| -| **refundAdj** | number | system | Refund amount associated with an invoice. It is calculated as the sum of all invoice payment amounts of type `REFUND` and `CHARGED_BACK`. | -| **invoiceDate** | date | system | Date when this invoice was generated | -| **targetDate** | date | user or system | Date up to which the account has been invoiced | -| **invoiceNumber** | number | system | Invoice number | -| **balance** | number | system | Invoice balance (amount that a customer owes as part of an invoice). At a high level, it is calculated as the sum of all item amounts minus the payment amount. See [Invoice Balance](https://docs.killbill.io/latest/invoice_examples.html#_invoice_balance) for further details. | -| **bundleKeys** | list | system |List of bundles invoiced. Deprecated. | -| **credits** | list | system | List of credits associated with this invoice. Deprecated. | -| **items** | list | system | List of invoice items on this invoice | -| **isParentInvoice** | boolean | system | If true, this invoice is the parent in the hierarchical model | -| **parentInvoiceId** | string | system | In the hierarchical model, UUID of the parent invoice | -| **parentAccountId** | string | system | In the hierarchical model, UUID of the parent account | - +| Name | Type | Generated by | Description | +|---------------------|---------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **invoiceId** | string | system | UUID for the invoice | +| **accountId** | string | system | UUID for the account | +| **amount** | number | user or system | Sum of all item amounts | +| **currency** | string | user or system | Currency associated with the account | +| **status** | string | system | Status of the invoice: DRAFT, COMMITTED or VOID | +| **creditAdj** | number | system | Invoice credit (amount that we owe to the customer). It is calculated as the sum of `CBA_ADJ` invoice items | +| **refundAdj** | number | system | Refund amount associated with an invoice. It is calculated as the sum of all invoice payment amounts of type `REFUND` and `CHARGED_BACK`. | +| **invoiceDate** | date | system | Date when this invoice was generated | +| **targetDate** | date | user or system | Date up to which the account has been invoiced | +| **invoiceNumber** | number | system | Invoice number | +| **balance** | number | system | Invoice balance (amount that a customer owes as part of an invoice). At a high level, it is calculated as the sum of all item amounts minus the payment amount. See [Invoice Balance](https://docs.killbill.io/latest/invoice_examples.html#_invoice_balance) for further details. | +| **bundleKeys** | list | system | List of bundles invoiced. Deprecated.| +| **credits** | list | system | List of credits associated with this invoice. Deprecated. | +| **items** | list | system | List of invoice items on this invoice. See Invoice Item resource below. | +| **trackingIds** | list | user | List of usage tracking ids associated with this invoice | +| **isParentInvoice** | boolean | system | If true, this invoice is the parent in the hierarchical model | +| **parentInvoiceId** | string | system | In the hierarchical model, UUID of the parent invoice | +| **parentAccountId** | string | system | In the hierarchical model, UUID of the parent account| +| **auditLogs** | array | system | Array of audit log records for this invoice| ## InvoiceItem Resource An `InvoiceItem` resource represents a single item charged on an invoice. The attributes contained in this resource are the following: -| Name | Type | Generated by | Description | -| ---- | -----| -------- | ------------ | -| **invoiceItemId** | string | system | UUID for the invoice item | -| **invoiceId** | string | system | UUID for the invoice | -| **linkedInvoiceItemId** | string |system | UUID for the linked item, if any (see below) | -| **accountId** | string | system | UUID for the account | -| **childAccountId** | string | system | In the hierarchical model, the UUID of the child account | -| **bundleId** | string | system | UUID for the bundle | -| **subscriptionId** | string | system | UUID for the subscription (present only if invoice item corresponds to a subscription) | -| **planName** | string | system | Name of the `Plan` for this subscription if any| -| **phaseName** | string | system | Name of the `PlanPhase` for this subscription if any| -| **usageName** | string | system | Name of the `Usage` section for this subscription if any| -| **prettyPlanName** | string | system | Pretty name of the `Plan` for this subscription if any| -| **prettyPhaseName** | string | system | Pretty name of the `PlanPhase` for this subscription if any| -| **prettyUsageName** | string | system | Pretty name of the `Usage` section for this subscription if any| -| **itemType** | string | system | Item type (see below) | -| **description** | string | user or system | Optional description of the item | -| **startDate** | date | user or system | Start date of the period invoiced | -| **endDate** | date | user or system | End date of the period invoiced | -| **amount** | number | user or system | Amount being invoiced | -| **quantity** | number | user or system | Rate associated with the `Plan` | -| **currency** | string | user or system | Currency associated with the account | -| **itemDetails** | string | user or system | In usage mode, details about what was invoiced. | -| **childItems** | list | user or system | In the hierarchical model, the items for the children. | +| Name | Type | Generated by | Description | +|--------------------------|----------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **invoiceItemId** | string | system | UUID for the invoice item | +| **invoiceId** | string | system | UUID for the invoice | +| **linkedInvoiceItemId** | string | system | UUID for the linked item, if any (see below) | +| **accountId** | string | system | UUID for the account | +| **childAccountId** | string | system | In the hierarchical model, the UUID of the child account | +| **bundleId** | string | system | UUID for the bundle | +| **subscriptionId** | string | system | UUID for the subscription (present only if invoice item corresponds to a subscription) | +| **productName** | string | system | Name of the `Product` for this subscription if any | +| **planName** | string | system | Name of the `Plan` for this subscription if any | +| **phaseName** | string | system | Name of the `PlanPhase` for this subscription if any | +| **usageName** | string | system | Name of the `Usage` section for this subscription if any | +| **prettyProductName** | string | system | Pretty name of the `Product` for this subscription if any | +| **prettyPlanName** | string | system | Pretty name of the `Plan` for this subscription if any | +| **prettyPhaseName** | string | system | Pretty name of the `PlanPhase` for this subscription if any | +| **prettyUsageName** | string | system | Pretty name of the `Usage` section for this subscription if any | +| **itemType** | string | system | Item type (see below) | +| **description** | string | user or system | Optional description of the item | +| **startDate** | date | user or system | Start date of the period invoiced | +| **endDate** | date | user or system | End date of the period invoiced | +| **amount** | number | user or system | Amount being invoiced | +| **rate** | number | user or system | Rate associated with the `Plan` | +| **currency** | string | user or system | Currency associated with the account | +| **quantity** | number | system | Quantity of usage blocks (number of units/block size). Applicable only for itemType=USAGE and when org.killbill.invoice.item.result.behavior.mode=DETAIL is specified | +| **itemDetails** | string | system | JSON list correpsonding to usage items being invoiced. It contains one entry per tier | +| **catalogEffectiveDate** | DateTime | system | The effective date of the underlying catalog. Applicable only for itemType=RECURRING | +| **childItems** | list | user or system | In the hierarchical model, the items for the children. | +| **auditLogs** | array | system | Array of audit log records for this invoice item | **linkedInvoiceItemId**: This ID is used to link to another item. For example, an item representing an adjustment would link to the item being adjusted. @@ -82,51 +88,51 @@ An `InvoiceItem` resource represents a single item charged on an invoice. The at * `RECURRING`: Recurring charge associated with a subscription. * `REPAIR_ADJ`: Internal adjustment generated by the system, used for billing in advance when the subscription state changed. * `CBA_ADJ`: Credit (positive or negative) generated by the system. -* `ITEM_ADJ`: Invoice item adjustment -- by itself or triggered by a refund. -* `USAGE`: Usage item -* `TAX`: Tax item -- this can only be added through an invoice plugin +* `ITEM_ADJ`: Invoice item adjustment - Typically generated by an operator and associated with a refund. +* `USAGE`: Usage charge associated with a subscription +* `TAX`: Tax item. * `PARENT_SUMMARY`: In the hierarchical model, represents the summary across all children Refer to the [Subscription Billing](https://docs.killbill.io/latest/userguide_subscription.html#components-invoicing) document for further details. ## InvoiceDryRun Resource -An `InvoiceDryRun` object represents an invoice preview generated to determine what would be in the invoice scheduled on a certain date, or if certain changes are made. A dry run has no actual effect on the system. The attributes contained in this resource are the following: +An `InvoiceDryRun` object encapsulates parameters that can be used to generate an invoice preview. Such an invoice preview can be generated to determine what would be in the invoice scheduled on a certain date, or if certain changes are made. A dry run has no actual effect on the system. The attributes contained in this resource are the following: -| Name | Type | Generated by | Description | -| ---- | -----| -------- | ------------ | -| **dryRunType** | string | user | Category for this dry run (see notes below) | -| **dryRunAction** | string | user | Action on which the dry run should be based, if any (see notes below) | -| **phaseType** | string | user | Type of the plan phase (see notes below) | -| **productName** | string | user | Name of the product subscribed | -| **productCategory** |string | user | Product category (see notes below) | -| **billingPeriod** | string | user | Billing period (see notes below) | -| **priceListName** | string | user | Name of the applicable price list | -| **subscriptiontId** | string | system | UUID for a subscription. If specified, only this subscription is used for the dry run | -| **bundleId** | string | system | UUID for a bundle. If specified, only this subscription is used for the dry run | -| **effectiveDate** | date | user | The date the change takes effect | -| **billingPolicy** | string | user | The billing policy (see notes below) | -| **priceOverrides** | list | user | list of prices if this subscription has price overrides | -| **planName** | string | user | Name of the plan subscribed | +| Name | Type | Generated by | Description | +|---------------------|--------|--------------|---------------------------------------------------------------------------------------| +| **dryRunType** | string | user | Category for this dry run (see notes below). | +| **dryRunAction** | string | user | Action on which the dry run should be based, if any (see notes below). Applicable only for `dryRunType=SUBSCRIPTION_ACTION`. | +| **phaseType** | string | user | Type of the plan phase (see notes below). | +| **productName** | string | user | Name of the product subscribed | +| **productCategory** | string | user | Product category (see notes below) | +| **billingPeriod** | string | user | Billing period (see notes below) | +| **priceListName** | string | user | Name of the applicable price list | +| **subscriptiontId** | string | system | UUID for a subscription. If specified, only this subscription is used for the dry run | +| **bundleId** | string | system | UUID for a bundle. If specified, only this subscription is used for the dry run | +| **effectiveDate** | date | user | The date the change takes effect | +| **billingPolicy** | string | user | The billing policy (see notes below) | +| **priceOverrides** | list | user | List of prices if this subscription has price overrides | +| **planName** | string | user | Name of the plan subscribed | -**dryRunType**: possible values are: +**dryRunType**: Possible values are: * TARGET_DATE -- Preview the invoice as of the given target date * UPCOMING_INVOICE -- Preview the next scheduled invoice -* SUBSCRIPTION_ACTION -- Preview the invoice that would be generated if the specified **dryRunAction** is taken +* SUBSCRIPTION_ACTION -- Preview the invoice that would be generated if the specified **dryRunAction** is taken. -**dryRunAction**: possible values are: START_BILLING, CHANGE (of `Plan`), or STOP_BILLING +**dryRunAction**: Possible values are: START_BILLING, CHANGE (of `Plan`), or STOP_BILLING -**phaseType**: possible values are: TRIAL, DISCOUNT, FIXEDTERM, or EVERGREEN +**phaseType**: Possible values are: TRIAL, DISCOUNT, FIXEDTERM, or EVERGREEN -**productCategory**: possible values are BASE, ADD_ON, or STANDALONE +**productCategory**: Possible values are BASE, ADD_ON, or STANDALONE -**billingPeriod**: possible values are DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, SIXTY_DAYS, NINETY_DAYS, MONTHLY, BIMESTRIAL (bimonthly), QUARTERLY, TRIANNUAL, BIANNUAL, ANNUAL, BIENNIAL, or NO_BILLING_PERIOD +**billingPeriod**: Possible values are DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, THIRTY_ONE_DAYS, SIXTY_DAYS, NINETY_DAYS, MONTHLY, BIMESTRIAL (bimonthly), QUARTERLY, TRIANNUAL, BIANNUAL, ANNUAL, SESQUIENNIAL, BIENNIAL, TRIENNIAL, or NO_BILLING_PERIOD. See [BillingPeriod](https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/catalog/api/BillingPeriod.java). -**billingPolicy**: possible values are START_OF_TERM, END_OF_TERM, or IMMEDIATE +**billingPolicy**: Possible values are START_OF_TERM, END_OF_TERM, or IMMEDIATE Note that either the `planName` or a combination of `productName`, `productCategory` and `billingPeriod` needs to be specified for the **START_BILLING**, **CHANGE** `dryRunAction`. @@ -175,8 +181,12 @@ Invoice invoice = invoiceApi.createFutureInvoice(accountId, targetDate, NULL_PLU ``` ```ruby +user = "demo" +reason = nil +comment = nil + account_id = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0" -target_date = nil +target_date = "2024-12-05" KillBillClient::Model::Invoice.trigger_invoice(account_id, target_date, @@ -188,15 +198,40 @@ KillBillClient::Model::Invoice.trigger_invoice(account_id, ```python invoiceApi = killbill.api.InvoiceApi() -target_date = datetime.date(2018, 6, 11) -invoiceApi.create_future_invoice(account_id, - created_by, - api_key, - api_secret, - target_date=target_date) +account_id = 'bdbed417-a84b-4303-958c-b88a36807416' +target_date = datetime.date(2023, 10, 20) + +invoiceApi.create_future_invoice(account_id, + target_date=target_date, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'b462d167-d9bc-459a-bdb7-23ebf99f5b76'; +const targetDate = '2023-10-21'; + +api.createFutureInvoice(accountId, 'created_by', targetDate); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$accountId = "d7ec4174-ab07-4e25-a917-ad020b755917"; +$targetDate = new \DateTime("2023-10-21"); +$pluginProperty = array("pluginProperty_example"); + +$result = $apiInstance->createFutureInvoice($accountId, $xKillbillCreatedBy, $targetDate, $pluginProperty, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** | Name | Type | Required | Default | Description | @@ -261,34 +296,76 @@ Invoice migrationInvoice = invoiceApi.createMigrationInvoice(accountId, ``` ```ruby -account_id = "be19b229-c076-47aa-aa4d-f53bec505dc7" -invoices = "external_invoice_list" +user = "demo" +reason = nil +comment = nil + +account_id = "3a949187-a2a0-46b5-8720-fff8b12eabff" target_date = "2018-03-15" -KillBillClient::Model::Invoice.create_migration_invoice(account_id, - invoices, - target_date, - user, - reason, - comment, + +invoice_item = KillBillClient::Model::InvoiceItem.new +invoice_item.item_type = "EXTERNAL_CHARGE" +invoice_item.amount = 50 +invoice_items = [invoice_item] + +KillBillClient::Model::Invoice.create_migration_invoice(account_id, + invoice_items, + target_date, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -body = 'external_invoice_list' -target_date = datetime.date(2018, 6, 11) + +account_id = 'bdbed417-a84b-4303-958c-b88a36807416' +body = InvoiceItem(account_id=account_id, + amount=50.0, + currency='USD', + item_type='EXTERNAL_CHARGE', + description='Migration item') invoiceApi.create_migration_invoice(account_id, [body], - created_by, - api_key, - api_secret, - target_date) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'b462d167-d9bc-459a-bdb7-23ebf99f5b76'; +const item: InvoiceItem = {amount: 10, itemType: "EXTERNAL_CHARGE",description:"a migration item"}; +const items = [item]; + +api.createMigrationInvoice(items, accountId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$item = new InvoiceItem(); +$item -> setAmount(100); +$item -> setItemType("EXTERNAL_CHARGE"); +$item -> setDescription("migration item"); +$body = array($item); + +$accountId = "f547bda2-ad09-4e79-84c3-9759939496dd"; +$targetDate = NULL; + +$result = $apiInstance->createMigrationInvoice($body, $xKillbillCreatedBy, $accountId, $xKillbillReason, $xKillbillComment, $targetDate); +```` + **Request Body** -An invoice resource object with all fields filled in representing the invoice to be migrated. At least the following fields need to be specified: itemType=EXTERNAL_CHARGE, amount. +A List of invoice item resource objects with all fields filled in representing the invoice to be migrated. At least the `itemType` and `amount` fields need to be specified. If multiple invoice items are specified, a single invoice is created with all the invoice items. **Query Parameters** @@ -353,6 +430,10 @@ List createdExternalCharges = invoiceApi.createExternalCharges(acco ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_item = KillBillClient::Model::InvoiceItem.new() invoice_item.account_id = "83e5e82d-fe72-4873-9b8b-946f4d250b0d" invoice_item.amount = '50.0' @@ -361,7 +442,7 @@ invoice_item.description = 'My charge' auto_commit = true -invoice_item.create(auto_commit, +invoice_item = invoice_item.create(auto_commit, user, reason, comment, @@ -370,19 +451,52 @@ invoice_item.create(auto_commit, ```python invoiceApi = killbill.api.InvoiceApi() + +account_id = 'bdbed417-a84b-4303-958c-b88a36807416' body = InvoiceItem(account_id=account_id, amount=50.0, currency='USD', - description='My charge') + description='External charge') -invoiceApi.create_external_charges(account_id, +invoice_item = invoiceApi.create_external_charges(account_id, [body], - created_by, - api_key, - api_secret, - auto_commit=True) + auto_commit=True, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'b462d167-d9bc-459a-bdb7-23ebf99f5b76'; +const item: InvoiceItem = {amount: 10, itemType: "EXTERNAL_CHARGE",description:"external charge"}; +const items = [item]; + +const response: AxiosResponse = await api.createExternalCharges(items, accountId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$item = new InvoiceItem(); +$item -> setAmount(100); +$item -> setItemType("EXTERNAL_CHARGE"); +$item -> setDescription("external charge item"); +$body = array($item); + +$accountId = "f547bda2-ad09-4e79-84c3-9759939496dd"; +$requestedDate = new \DateTime("2023-09-21"); +$autoCommit = false; +$pluginProperty = array("pluginProperty_example"); + +$result = $apiInstance->createExternalCharges($body, $xKillbillCreatedBy, $accountId, $xKillbillReason, $xKillbillComment, $requestedDate, $autoCommit, $pluginProperty); +```` + > Example Response: ```json @@ -412,6 +526,7 @@ invoiceApi.create_external_charges(account_id, "currency": "USD", "quantity": null, "itemDetails": null, + "catalogEffectiveDate":null, "childItems": null, "auditLogs": [] } @@ -420,7 +535,7 @@ invoiceApi.create_external_charges(account_id, **Request Body** -An invoice item resource object with at least the `amount` attribute. If multiple invoice items are specified, a single invoice is created with all the invoice items. +A List of invoice item resource objects with at least the `amount` attribute populated. If multiple invoice items are specified, a single invoice is created with all the invoice items. **Query Parameters** @@ -429,6 +544,7 @@ An invoice item resource object with at least the `amount` attribute. If multipl | ---- | -----| -------- | ------- | ----------- | | **requestedDate** | string | no | current date | requested date | | **autoCommit** | boolean | no | false | If true, the resulting invoice should be COMMITTED. | +| **pluginProperty** | array of strings | no | omit | list of plugin properties, if any. Should be in the format `key%3Dvalue` | **Response** @@ -465,7 +581,7 @@ import org.killbill.billing.client.api.gen.InvoiceApi; protected InvoiceApi invoiceApi; UUID accountId = UUID.fromString("eb36c64c-b575-4538-b26f-a89c473984da"); -UID bundleId = UUID.fromString("28723cec-5510-49be-9e87-3a36d246f25e"); +UUID bundleId = UUID.fromString("28723cec-5510-49be-9e87-3a36d246f25e"); InvoiceItem taxItem = new InvoiceItem(); taxItem.setAccountId(accountId); @@ -476,7 +592,7 @@ final InvoiceItems input = new InvoiceItems(); input.add(taxItem); Boolean autoCommit = true; -LocalDate requestedDate = clock.getUTCToday(); +LocalDate requestedDate = null; Map pluginProperty = null; List createdTaxItems = invoiceApi.createTaxItems(accountId, @@ -488,36 +604,73 @@ List createdTaxItems = invoiceApi.createTaxItems(accountId, ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_item = KillBillClient::Model::InvoiceItem.new() -invoice_item.account_id = "29ef0d50-90d1-4163-bb46-ef1b82675ae6" +invoice_item.account_id = "3a949187-a2a0-46b5-8720-fff8b12eabff" invoice_item.amount = '50.0' invoice_item.currency = 'USD' -invoice_item.description = 'My charge' +invoice_item.description = 'Tax item' auto_commit = true -invoice_item.create_tax_items(auto_commit, - user, - reason, - comment, +invoice_item = invoice_item.create_tax_item(auto_commit, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() + +account_id = 'bdbed417-a84b-4303-958c-b88a36807416' body = InvoiceItem(account_id=account_id, amount=50.0, currency='USD', - description='My charge') + description='Tax item') -invoiceApi.create_tax_items(account_id, +invoice_item = invoiceApi.create_tax_items(account_id, [body], - created_by, - api_key, - api_secret, - auto_commit=True) + auto_commit=True, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'b462d167-d9bc-459a-bdb7-23ebf99f5b76'; +const item: InvoiceItem = {amount: 10, itemType: "TAX",description:"a tax item"}; +const items = [item]; + +const response: AxiosResponse = await api.createTaxItems(items, accountId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$item = new InvoiceItem(); +$item -> setAmount(100); +$item -> setItemType("TAX"); +$item -> setDescription("tax item"); +$body = array($item); + +$accountId = "f547bda2-ad09-4e79-84c3-9759939496dd"; +$requestedDate = new \DateTime("2023-09-21"); +$autoCommit = false; +$pluginProperty = array("pluginProperty_example"); + +$result = $apiInstance->createTaxItems($body, $xKillbillCreatedBy, $accountId, $xKillbillReason, $xKillbillComment, $autoCommit, $requestedDate, $pluginProperty); +```` + > Example Response: ```json @@ -547,6 +700,7 @@ invoiceApi.create_tax_items(account_id, "currency": "USD", "quantity": null, "itemDetails": null, + "catalogEffectiveDate":null, "childItems": null, "auditLogs": [] } @@ -555,7 +709,7 @@ invoiceApi.create_tax_items(account_id, **Request Body** -An invoice item resource object with at least the `amount` attribute. +A List of invoice item resource objects with at least the `amount` attribute populated. If multiple invoice items are specified, a single invoice is created with all the invoice items. **Query Parameters** @@ -563,6 +717,7 @@ An invoice item resource object with at least the `amount` attribute. | ---- | -----| -------- | ------- | ----------- | | **requestedDate** | string | no | current date | requested date | | **autoCommit** | boolean | no | false | If true, the resulting invoice should be COMMITTED. | +| **pluginProperty** | array of strings | no | omit | list of plugin properties, if any. Should be in the format `key%3Dvalue` | **Response** @@ -593,7 +748,7 @@ import org.killbill.billing.client.api.gen.InvoiceApi; protected InvoiceApi invoiceApi; UUID invoiceId = UUID.fromString("922a83f4-ae08-4732-9dd9-35e13c332393"); -Boolean withChildrenItems = false; // Will include children items +Boolean withChildrenItems = true; // Will include children items Invoice invoiceWithItems = invoiceApi.getInvoice(invoiceId, withChildrenItems, @@ -602,40 +757,88 @@ Invoice invoiceWithItems = invoiceApi.getInvoice(invoiceId, ``` ```ruby -invoice_id = "31db9f9a-91ff-49f4-b5a1-5e4fce59a197" -with_items = true +invoice_id = "5c6083c1-a673-4b67-9b86-74139df50448" audit = 'NONE' -KillBillClient::Model::Invoice.find_by_id(invoice_id, - with_items, - audit, +invoice = KillBillClient::Model::Invoice.find_by_id(invoice_id, + audit, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '43da4e9c-03c6-4f15-8943-b9a3af3ecacb' - -invoiceApi.get_invoice(invoice_id, api_key, api_secret) +invoice_id = '4b16ad29-2f32-4e7e-85f9-99beda4ae7dd' + +invoice = invoiceApi.get_invoice(invoice_id) ``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = 'fd9df8b8-f845-43a1-8fe8-73a8269c5bcc'; + +const response: AxiosResponse = await api.getInvoice(invoiceId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "0fd7d64a-90d2-4d4d-9123-e9c5c7f36a47"; +$withChildrenItems = false; +$audit = "NONE"; + +$result = $apiInstance->getInvoice($invoiceId, $withChildrenItems, $audit); +```` + > Example Response: ```json { - "amount": 0, + "amount": 50, "currency": "USD", - "status": "DRAFT", - "creditAdj": 50, + "status": "COMMITTED", + "creditAdj": 0, "refundAdj": 0, - "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5", - "invoiceDate": "2018-07-20", - "targetDate": "2018-07-20", - "invoiceNumber": "310", - "balance": 0, - "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "invoiceDate": "2023-09-18", + "targetDate": "2023-09-18", + "invoiceNumber": "6894", + "balance": 50, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", "bundleKeys": null, "credits": null, - "items": [], + "items": [ + { + "invoiceItemId": "af65fae9-1dd9-4340-87cb-8d2e9d7ed3d8", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "linkedInvoiceItemId": null, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", + "childAccountId": null, + "bundleId": null, + "subscriptionId": null, + "productName": null, + "planName": null, + "phaseName": null, + "usageName": null, + "prettyProductName": null, + "prettyPlanName": null, + "prettyPhaseName": null, + "prettyUsageName": null, + "itemType": "TAX", + "description": "Tax", + "startDate": "2023-09-18", + "endDate": null, + "amount": 50, + "rate": null, + "currency": "USD", + "quantity": null, + "itemDetails": null, + "catalogEffectiveDate": null, + "childItems": null, + "auditLogs": [] + } + ], + "trackingIds": [], "isParentInvoice": false, "parentInvoiceId": null, "parentAccountId": null, @@ -645,12 +848,10 @@ invoiceApi.get_invoice(invoice_id, api_key, api_secret) **Query Parameters** -| Name | Type | Required | Default | Description | -| ---- | -----| -------- | ------- | ----------- | -| **withChildrenItems** | boolean | no | false | If true, include children items | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| Name | Type | Required | Default | Description | +| ---- | -----| -------- | ------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **withChildrenItems** | boolean | no | false | If true, include children items (applicable only in the hierarchical mode if the current invoice corresponds to a parent invoice and isPaymentDelegatedToParent=true). | +| **audit** | string | no | "NONE" | Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL" | **Returns** @@ -680,7 +881,7 @@ import org.killbill.billing.client.api.gen.InvoiceApi; protected InvoiceApi invoiceApi; Integer invoiceNumber = 1; -Boolean withChildrenItems = false; // Will include children items +Boolean withChildrenItems = false; // Will not include children items Invoice invoiceByNumber = invoiceApi.getInvoiceByNumber(invoiceNumber, withChildrenItems, @@ -689,40 +890,88 @@ Invoice invoiceByNumber = invoiceApi.getInvoiceByNumber(invoiceNumber, ``` ```ruby -invoice_number = "1913" -with_items = true +invoice_number = "7318" audit = 'NONE' -KillBillClient::Model::Invoice.find_by_number(invoice_number, - with_items, - audit, +invoice = KillBillClient::Model::Invoice.find_by_number(invoice_number, + audit, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_number = '972' +invoice_number = '7452' -invoiceApi.get_invoice_by_number(invoice_number, api_key, api_secret) +invoice = invoiceApi.get_invoice_by_number(invoice_number) ``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceNumber = 7463; + +const response: AxiosResponse = await api.getInvoiceByNumber(invoiceNumber); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceNumber = 7457; +$withChildrenItems = false; +$audit = "NONE"; + +$result = $apiInstance->getInvoiceByNumber($invoiceNumber, $withChildrenItems, $audit); +```` + > Example Response: ```json { - "amount": 0, + "amount": 50, "currency": "USD", - "status": "DRAFT", - "creditAdj": 50, + "status": "COMMITTED", + "creditAdj": 0, "refundAdj": 0, - "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5", - "invoiceDate": "2018-07-20", - "targetDate": "2018-07-20", - "invoiceNumber": "310", - "balance": 0, - "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "invoiceDate": "2023-09-18", + "targetDate": "2023-09-18", + "invoiceNumber": "6894", + "balance": 50, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", "bundleKeys": null, "credits": null, - "items": [], + "items": [ + { + "invoiceItemId": "af65fae9-1dd9-4340-87cb-8d2e9d7ed3d8", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "linkedInvoiceItemId": null, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", + "childAccountId": null, + "bundleId": null, + "subscriptionId": null, + "productName": null, + "planName": null, + "phaseName": null, + "usageName": null, + "prettyProductName": null, + "prettyPlanName": null, + "prettyPhaseName": null, + "prettyUsageName": null, + "itemType": "TAX", + "description": "Tax", + "startDate": "2023-09-18", + "endDate": null, + "amount": 50, + "rate": null, + "currency": "USD", + "quantity": null, + "itemDetails": null, + "catalogEffectiveDate": null, + "childItems": null, + "auditLogs": [] + } + ], + "trackingIds": [], "isParentInvoice": false, "parentInvoiceId": null, "parentAccountId": null, @@ -732,12 +981,10 @@ invoiceApi.get_invoice_by_number(invoice_number, api_key, api_secret) **Query Parameters** -| Name | Type | Required | Default | Description | -| ---- | -----| -------- | ------- | ----------- | -| **withChildrenItems** | boolean | no | false | If true, include children items | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| Name | Type | Required | Default | Description | +| ---- | -----| -------- | ------- |----------------------------------------------------------------------------------| +| **withChildrenItems** | boolean | no | false | If true, include children items (applicable only in the hierarchical mode if the current invoice corresponds to a parent invoice and isPaymentDelegatedToParent=true).| +| **audit** | string | no | "NONE" | Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL" | **Returns** @@ -745,7 +992,7 @@ If successful, returns a status code of 200 and an invoice resource object. ### Retrieve an invoice by invoice item id -Retrieves an invoice based on the `invoiceItemId` for an invoice item. +Retrieves an invoice based on the `invoiceItemId` corresponding to an invoice item. **HTTP Request** @@ -766,8 +1013,8 @@ curl -v \ import org.killbill.billing.client.api.gen.InvoiceApi; protected InvoiceApi invoiceApi; -UUID invoiceItemId = UUID.fromString("111732ad-196d-423f-8ccd-de44109dc944") -Boolean withChildrenItems = false; // Will include children items +UUID invoiceItemId = UUID.fromString("111732ad-196d-423f-8ccd-de44109dc944"); +Boolean withChildrenItems = false; // Will not include children items Invoice invoiceByItemId = invoiceApi.getInvoiceByItemId(invoiceItemId, withChildrenItems, @@ -776,45 +1023,91 @@ Invoice invoiceByItemId = invoiceApi.getInvoiceByItemId(invoiceItemId, ``` ```ruby -invoice_item_id = "f641ce8a-a874-4e98-ada5-2bd8fdb74945" -with_items = true +invoice_item_id = "14b0de07-6634-4e56-9062-156ba8e6c06d" with_children_items = false audit = 'NONE' -KillBillClient::Model::Invoice.find_by_invoice_item_id(invoice_item_id, - with_items, - with_children_items, - audit, +invoice = KillBillClient::Model::Invoice.find_by_invoice_item_id(invoice_item_id, + with_children_items, + audit, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_item_id = '8fae6721-3ebc-4103-85f5-aa13dde0e4f5' +invoice_item_id = '5cc1dce5-7f95-4d8e-987b-27ddd9e5b171' -invoiceApi.get_invoice_by_item_id(invoice_item_id, - api_key, - api_secret, - with_items=True) +invoice = invoiceApi.get_invoice_by_item_id(invoice_item_id, + with_children_items=True) ``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceItemId = 'ed7e1b5d-ed43-41bf-99ca-85ff2c88462d'; + +const response: AxiosResponse = await api.getInvoiceByItemId(invoiceItemId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$itemId = "b912e57d-897c-4018-9802-66a030fad55f"; +$withChildrenItems = false; +$audit = "NONE"; + +$result = $apiInstance->getInvoiceByItemId($itemId, $withChildrenItems, $audit); +```` + > Example Response: ```json { - "amount": 0, + "amount": 50, "currency": "USD", - "status": "DRAFT", - "creditAdj": 50, + "status": "COMMITTED", + "creditAdj": 0, "refundAdj": 0, - "invoiceId": "18e9b3d9-9083-4725-9e8a-27d3a57c2e88", - "invoiceDate": "2018-07-20", - "targetDate": "2018-07-20", - "invoiceNumber": "311", - "balance": 0, - "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "invoiceDate": "2023-09-18", + "targetDate": "2023-09-18", + "invoiceNumber": "6894", + "balance": 50, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", "bundleKeys": null, "credits": null, - "items": [], + "items": [ + { + "invoiceItemId": "af65fae9-1dd9-4340-87cb-8d2e9d7ed3d8", + "invoiceId": "4bc38bfd-3210-4293-bcfc-7c95b2d1472a", + "linkedInvoiceItemId": null, + "accountId": "d7ec4174-ab07-4e25-a917-ad020b755917", + "childAccountId": null, + "bundleId": null, + "subscriptionId": null, + "productName": null, + "planName": null, + "phaseName": null, + "usageName": null, + "prettyProductName": null, + "prettyPlanName": null, + "prettyPhaseName": null, + "prettyUsageName": null, + "itemType": "TAX", + "description": "Tax", + "startDate": "2023-09-18", + "endDate": null, + "amount": 50, + "rate": null, + "currency": "USD", + "quantity": null, + "itemDetails": null, + "catalogEffectiveDate": null, + "childItems": null, + "auditLogs": [] + } + ], + "trackingIds": [], "isParentInvoice": false, "parentInvoiceId": null, "parentAccountId": null, @@ -826,10 +1119,8 @@ invoiceApi.get_invoice_by_item_id(invoice_item_id, | Name | Type | Required | Default | Description | | ---- | -----| -------- | ------- | ----------- | -| **withChildrenItems** | boolean | no | false | If true, include children items | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| **withChildrenItems** | boolean | no | false | If true, include children items (applicable only in the hierarchical mode if the current invoice corresponds to a parent invoice and isPaymentDelegatedToParent=true).| +| **audit** | string | no | "NONE" | Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL" | **Response** @@ -864,17 +1155,33 @@ String htmlInvoice = invoiceApi.getInvoiceAsHTML(invoiceId, requestOptions); ``` ```ruby -invoice_id = invoice.invoice_id -KillBillClient::Model::Invoice.as_html(invoice_id, @options) +invoice_id = "5c6083c1-a673-4b67-9b86-74139df50448" +invoiceHTML = KillBillClient::Model::Invoice.as_html(invoice_id, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '2c98cfa2-7929-4cc2-9397-1624fb72c6d5' +invoice_id = '4b16ad29-2f32-4e7e-85f9-99beda4ae7dd' -invoiceApi.get_invoice_as_html(invoice_id, api_key, api_secret) +invoiceHTML = invoiceApi.get_invoice_as_html(invoice_id) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = 'fd9df8b8-f845-43a1-8fe8-73a8269c5bcc'; + +const response: AxiosResponse = await api.getInvoiceAsHTML(invoiceId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "0fd7d64a-90d2-4d4d-9123-e9c5c7f36a47"; + +$result = $apiInstance->getInvoiceAsHTML($invoiceId); +```` + > Example Response: ```text/plain @@ -988,12 +1295,12 @@ None. **Response** -If successful, returns a status code of 200 and an invoice rendered as HTML. +If successful, returns a status code of 200 and an HTML string corresponding to the invoice. ### Change invoice status from DRAFT to COMMITTED -Commit a DRAFT invoice by changing its staus to COMMITTED. The invoice becomes immutable and its balance is now included in account totals. +Commit a DRAFT invoice by changing its status to COMMITTED. The invoice becomes immutable and its balance is now included in account totals. **HTTP Request** @@ -1025,6 +1332,10 @@ invoiceApi.commitInvoice(invoiceId, requestOptions); ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice = KillBillClient::Model::Invoice.new invoice.invoice_id = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5" @@ -1036,13 +1347,34 @@ invoice.commit(user, ```python invoiceApi = killbill.api.InvoiceApi() +invoice_id = '18d23ef1-ea82-442d-8602-43305232f3e5' -invoiceApi.commit_invoice(invoice_id, - created_by, - api_key, - api_secret) +invoiceApi.commit_invoice(invoice_id, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = '926ff247-e220-4cf9-8829-c13e943e3809'; + +api.commitInvoice(invoiceId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "80bd3bf3-307f-438b-bf7a-7dc5e8addf19"; + +$apiInstance->commitInvoice($invoiceId, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** None. @@ -1090,19 +1422,49 @@ invoiceApi.voidInvoice(invoiceId, requestOptions); ``` ```ruby -TODO +user = "demo" +reason = nil +comment = nil + +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = "6b877adc-0916-4409-ba95-f4e955772ea6" + +invoice.void(user, + reason, + comment, + options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069' +invoice_id = '18d23ef1-ea82-442d-8602-43305232f3e5' -invoiceApi.void_invoice(invoice_id, - created_by, - api_key, - api_secret) +invoiceApi.void_invoice(invoice_id, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = '926ff247-e220-4cf9-8829-c13e943e3809'; + +api.voidInvoice(invoiceId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "80bd3bf3-307f-438b-bf7a-7dc5e8addf19"; + +$apiInstance->voidInvoice($invoiceId, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** None. @@ -1113,7 +1475,9 @@ If successful, returns a status code of 204 and an empty body. ### Adjust an invoice item -Adjust the amount for an invoice item +Adjust the amount for an invoice item. The system adds a new invoice item of type `ITEM_ADJ` to the invoice. If the invoice was already paid for, the system also adds another invoice item of type `CBA_ADJ` to adjust the credit amount in the next invoice. See [Invoice Examples](https://docs.killbill.io/latest/invoice_examples#_invoice_item_adjustment) for more information. + +**Notes:** The `linkedInvoiceItemId` field of the new invoice item points to the id of the invoice item being adjusted. **HTTP Request** @@ -1163,6 +1527,10 @@ Invoice result = invoiceApi.adjustInvoiceItem(invoiceId, ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_item = KillBillClient::Model::InvoiceItem.new invoice_item.account_id = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0" invoice_item.invoice_id = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5" @@ -1179,29 +1547,61 @@ invoice_item.update(user, ```python invoiceApi = killbill.api.InvoiceApi() -body = InvoiceItem(account_id='3ee3aa82-1d45-4bbc-b36b-74d628e095d0', - invoice_id='2c98cfa2-7929-4cc2-9397-1624fb72c6d5', - invoice_item_id='b311f709-ad51-4f67-8722-18ce04334c31', - amount=100, +invoice_id = '4b16ad29-2f32-4e7e-85f9-99beda4ae7dd' +body = InvoiceItem(account_id='bdbed417-a84b-4303-958c-b88a36807416', + invoice_id='4b16ad29-2f32-4e7e-85f9-99beda4ae7dd', + invoice_item_id='5cc1dce5-7f95-4d8e-987b-27ddd9e5b171', + amount=10, currency='USD', description='Free adjustment: good customer') invoiceApi.adjust_invoice_item(invoice_id, body, - created_by, - api_key, - api_secret) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const item: InvoiceItem = {accountId: "b462d167-d9bc-459a-bdb7-23ebf99f5b76", invoiceId: "4f948961-90a9-427b-bfbf-7583bee86711",invoiceItemId:"3fd23760-11be-447d-8c91-9a22037ca239", amount:10, description: "free adjustment, good customer"}; +const invoiceId = '4f948961-90a9-427b-bfbf-7583bee86711'; + +api.adjustInvoiceItem(item, invoiceId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "b7c4ce68-e885-4f8b-8ee3-2eee7b3d8fb7"; +$requestedDate = NULL; +$pluginProperty = array("pluginProperty_example"); + +$body = new InvoiceItem(); +$body -> setAmount(20); +$body -> setAccountId("f547bda2-ad09-4e79-84c3-9759939496dd"); +$body -> setInvoiceId($invoiceId); +$body -> setInvoiceItemId("00450fb0-25c2-4ad4-ac81-8d3258ec6b25"); +$body -> setDescription("good customer - free adjustment"); + +$result = $apiInstance->adjustInvoiceItem($body, $xKillbillCreatedBy, $invoiceId, $xKillbillReason, $xKillbillComment, $requestedDate, $pluginProperty); +```` + **Request Body** -An invoice item resource object with at least `invoiceItemId`, `invoiceId`, and `amount` attributes. +An invoice item resource object with at least `accountId`, `invoiceItemId`, `invoiceId`, and `amount` attributes. **Query Parameters** | Name | Type | Required | Default | Description | | ---- | -----| -------- | ------- | ----------- | | **requestedDate** | string | no | current date | requested date | +| **pluginProperty** | array of strings | no | omit | list of plugin properties, if any. Should be in the format `key%3Dvalue` | **Returns** @@ -1212,13 +1612,17 @@ If successful, returns a status code of 201 and an empty body. In addition, a `L Delete a Credit Balance Adjust (`CBA_ADJ`) invoice item. There are some limitations and side effects with this api: -1. Deleting a positive `CBA_ADJ` (credit generation), may lead the system to reclaim portion of the used credit, possibly leaving some invoices with a balance. Example: +**Deleting a positive `CBA_ADJ` (credit generation), may lead the system to reclaim portion of the used credit, possibly leaving some invoices with a balance.** + +Given an invoice, I1, where user added some credit ($12), we would see the following items: {`CREDIT_ADJ`: -12, `CBA_ADJ`: +12}. Given another invoice, I2, where the system invoiced for a recurring subscription, and where some of this credit was consumed, we would see the following items: {`RECURRING`: +10, `CBA_ADJ`: -10}. Deleting the `CBA_ADJ` from I1, would lead to the following resulting invoices: I1 {`CREDIT_ADJ`: 0, `CBA_ADJ`: 0} and I2 {`RECURRING`: +10, `CBA_ADJ`: 0}. The system zeroed-out the credit generation and the part that was used, and as a result I2 would be left with a balance of +10. + +**Deleting a negative `CBA_ADJ` would also leave invoice with a balance.** -Given an invoice, I1, where user added some credit ($12), we would see the following items: {`CREDIT_ADJ`: -12, `CBA_ADJ`: +12}. Given another invoice, I2, where the system invoiced for a recurring subscription, and where some of this credit was consumed, we would see the following items: {`RECURRING`: +10, `CBA_ADJ`: -10}. Deleting the `CBA_ADJ` from I1, would lead to the following resulting invoices: I1 {`CREDIT_ADJ`: 0, `CBA_ADJ`: 0} and I2 {`RECURRING`: +10, `CBA_ADJ`: 0}. The system zeroed-out the credit generation and the part that was used, and as a result I2 would be left with a balance of +10. Deleting the `CBA_ADJ` from I2 on the other hand would lead to the following invoice: I2 {`RECURRING`: +20, `CBA_ADJ`: 0} . +So deleting the `CBA_ADJ` from I2 in the example above would lead to the following invoice: I2 {`RECURRING`: +10, `CBA_ADJ`: 0} . -2. System generated credit +**Attempting to delete system generated credit would fail.** -In an in-advanced scenario where the system first invoiced for a recurring subscription ($20), and then repaired ($-8) for instance as a result of an early cancelation, we would have the following invoices: I1 {`RECURRING`: +20} and I2 {`REPAIR_ADJ`: -8, `CBA_ADJ`: +8}. Attempting to delete the `CBA_ADJ` on I2 would fail as the generation of credit was system generated, i.e it happened as a result of a subscription change. +In an in-advanced scenario where the system first invoiced for a recurring subscription ($20), and then repaired ($-8) for instance as a result of an early cancelation, we would have the following invoices: I1 {`RECURRING`: +20} and I2 {`REPAIR_ADJ`: -8, `CBA_ADJ`: +8}. Attempting to delete the `CBA_ADJ` on I2 would fail as the generation of credit was system generated, i.e. it happened as a result of a subscription change. **HTTP Request** @@ -1247,6 +1651,10 @@ invoiceApi.deleteCBA(invoiceId, invoiceItemId, accountId, requestOptions); ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_item = KillBillClient::Model::InvoiceItem.new invoice_item.account_id = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0" invoice_item.invoice_id = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5" @@ -1260,18 +1668,42 @@ invoice_item.delete(user, ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id='2c98cfa2-7929-4cc2-9397-1624fb72c6d5', -invoice_item_id='b311f709-ad51-4f67-8722-18ce04334c31' -account_id = '3ee3aa82-1d45-4bbc-b36b-74d628e095d0', +invoice_id='a493320b-29ab-4228-ad84-58d53e88b73b' +invoice_item_id='b3aeb9d7-4501-4285-8071-f5c02f45a659' +account_id = 'bdbed417-a84b-4303-958c-b88a36807416' invoiceApi.delete_cba(invoice_id, invoice_item_id, account_id, - created_by, - api_key, - api_secret) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'b462d167-d9bc-459a-bdb7-23ebf99f5b76'; +const invoiceId = 'd723f109-7c4d-470e-9267-995610b02b28'; +const invoiceItemId = '7b8d4e3e-0fa0-43fc-bac2-4a0147e9a185'; + +api.deleteCBA(invoiceId, invoiceItemId, accountId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "dff3b38a-4fcd-43f7-8fe9-7dcae2bc8269"; +$invoiceItemId = "177cba3a-6775-4357-94cc-0f1e51136649"; +$accountId = "f547bda2-ad09-4e79-84c3-9759939496dd"; + +$apiInstance->deleteCBA($invoiceId, $invoiceItemId, $accountId, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** | Name | Type | Required | Default | Description | @@ -1311,6 +1743,7 @@ in the system. > Example Request: ```shell +# For targetDate curl -v \ -X POST \ -u admin:password \ @@ -1326,6 +1759,7 @@ curl -v \ OR +# upcoming invoice curl -v \ -X POST \ -u admin:password \ @@ -1339,8 +1773,25 @@ curl -v \ -d '{ "dryRunType": "UPCOMING_INVOICE"}' \ "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=2ad52f53-85ae-408a-9879-32a7e59dd03d" +OR + +# START_BILLING +curl -v \ + -X POST \ + -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "X-Killbill-CreatedBy: demo" \ + -H "X-Killbill-Reason: demo" \ + -H "X-Killbill-Comment: demo" \ + -d '{ "dryRunType": "SUBSCRIPTION_ACTION","dryRunAction":"START_BILLING","planName":"pistol-monthly-notrial"}' \ + "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=b462d167-d9bc-459a-bdb7-23ebf99f5b76" + OR +# CHANGE curl -v \ -X POST \ -u admin:password \ @@ -1356,6 +1807,7 @@ curl -v \ OR +# STOP_BILLING curl -v \ -X POST \ -u admin:password \ @@ -1367,8 +1819,7 @@ curl -v \ -H "X-Killbill-Reason: demo" \ -H "X-Killbill-Comment: demo" \ -d '{ "dryRunType": "SUBSCRIPTION_ACTION","dryRunAction":"STOP_BILLING","subscriptionId":"0b9efead-d5e4-40a9-8178-2286dee0fe48","bundleId":" 6ebcc573-c2c4-408a-b5c3-d6ae0dbae233","effectiveDate":"2022-02-10"}' \ - "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6" - + "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6" ``` @@ -1388,28 +1839,33 @@ UUID bundleId = null; LocalDate effectiveDate = null; BillingActionPolicy billingPolicy = null; List priceOverrides = null; +String planName = null; -InvoiceDryRun dryRunArg = new InvoiceDryRun(dryRunType, - dryRunAction, - phaseType, - productName, - productCategory, - billingPeriod, - priceListName, - subscriptionId, - bundleId, - effectiveDate, - billingPolicy, - priceOverrides); - - -UUID accountId = UUID.fromString("fe1a6f86-9ec5-4ac3-8d39-15f024cc8339"); -LocalDate targetDate = new LocalDate().plusDays(1); +Map NULL_PLUGIN_PROPERTIES = null; -Invoice dryRunInvoice = invoiceApi.generateDryRunInvoice(dryRunArg, - accountId, - targetDate, - requestOptions); +InvoiceDryRun dryRunArg = new InvoiceDryRun(dryRunType, + dryRunAction, + phaseType, + productName, + productCategory, + billingPeriod, + priceListName, + subscriptionId, + bundleId, + effectiveDate, + billingPolicy, + priceOverrides, + planName); + + +UUID accountId = UUID.fromString("8452df66-ded8-4fba-b7dc-50302d19bc5b"); +LocalDate targetDate = new LocalDate("2023-10-22"); + +Invoice dryRunInvoice = invoiceApi.generateDryRunInvoice(dryRunArg, + accountId, + targetDate, + NULL_PLUGIN_PROPERTIES, + requestOptions); ``` ```ruby @@ -1436,13 +1892,39 @@ invoiceApi = killbill.api.InvoiceApi() body = InvoiceDryRun(dry_run_type='UPCOMING_INVOICE') account_id = '00e87495-92dc-4640-8490-e2c794748151' -invoiceApi.generate_dry_run_invoice(body, - account_id, - created_by, - api_key, - api_secret) +invoice = invoiceApi.generate_dry_run_invoice(body, + account_id, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = 'a24a1b9f-9d0f-4311-ad05-feac80f7b177'; +const targetDate = '2023-10-26'; +const invoiceDryRun: InvoiceDryRun = {dryRunType: "UPCOMING_INVOICE"}; + +const response: AxiosResponse = await api.generateDryRunInvoice(invoiceDryRun, accountId, 'created_by', targetDate); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$body = new InvoiceDryRun(); +$body -> setDryRunType("UPCOMING_INVOICE"); +$accountId = "a24a1b9f-9d0f-4311-ad05-feac80f7b177"; +$targetDate = null; +$pluginProperty = array("pluginProperty_example"); + +$result = $apiInstance->generateDryRunInvoice($body, $xKillbillCreatedBy, $accountId, $xKillbillReason, $xKillbillComment, $targetDate, $pluginProperty); +```` + > Example Response: ```json @@ -1546,6 +2028,7 @@ A [dry run resource object](invoice.html#invoice-invoicedryrun-resource). The ** | ---- | -----| -------- | ------- | ----------- | | **accountId** | string | yes | none | Account id | | **targetDate** | string | No | current date | Target date is the invoicing target date | +| **pluginProperty** | array of strings | no | omit | list of plugin properties, if any. Should be in the format `key%3Dvalue` | Note that for `SUBSCRIPTION_ACTION`, there are 2 dates to take into account: @@ -1606,9 +2089,41 @@ TODO ``` ```python -TODO +invoiceApi = killbill.api.InvoiceApi() + +account_id = '8452df66-ded8-4fba-b7dc-50302d19bc5b' +target_date = datetime.date(2023, 11, 22) + +invoiceApi.create_future_invoice_group(account_id, + target_date=target_date, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = '8452df66-ded8-4fba-b7dc-50302d19bc5b'; +const targetDate = '2024-02-22'; + +api.createFutureInvoiceGroup(accountId, 'created_by', targetDate); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$accountId = "8452df66-ded8-4fba-b7dc-50302d19bc5b"; +$targetDate = new DateTime("2024-04-22"); +$pluginProperty = array("pluginProperty_example"); + +$result = $apiInstance->createFutureInvoiceGroup($accountId, $xKillbillCreatedBy, $targetDate, $pluginProperty, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** | Name | Type | Required | Default | Description | @@ -1656,8 +2171,34 @@ TODO ``` ```python -TODO +invoiceApi = killbill.api.InvoiceApi() + +account_id = '8452df66-ded8-4fba-b7dc-50302d19bc5b' +group_id = '51eae3dc-eec8-4ffa-b7d1-65b7b797538e' + +invoice_group = invoiceApi.get_invoices_group(group_id, account_id) ``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const accountId = '8452df66-ded8-4fba-b7dc-50302d19bc5b'; +const groupId = 'ad2921d2-a343-4115-9a51-32288f49e6f0'; + +const response: AxiosResponse = await api.getInvoicesGroup(groupId, accountId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$groupId = "ad2921d2-a343-4115-9a51-32288f49e6f0"; +$accountId = "8452df66-ded8-4fba-b7dc-50302d19bc5b"; +$withChildrenItems = false; +$audit = "NONE"; + +$result = $apiInstance->getInvoicesGroup($groupId, $accountId, $withChildrenItems, $audit); +```` + > Example Response: ```json @@ -1773,9 +2314,7 @@ TODO | ---- | -----| -------- | ------- | ----------- | | **accountId** | string | yes| none| accountId| | **withChildrenItems** | boolean | no | false | If true, include children items | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| **audit** | string | no | "NONE" | Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL" | **Returns** If successful, returns a status code of 200 and a list of invoice objects for this group. @@ -1808,7 +2347,7 @@ curl -v \ -H "X-Killbill-Reason: demo" \ -H "X-Killbill-Comment: demo" \ -d '{ "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "purchasedAmount": 50, "targetInvoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5"}' \ - "http://localhost:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/payments?externalPayment=false" + "http://localhost:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/payments" ``` ```java @@ -1825,61 +2364,103 @@ invoicePayment.setTargetInvoiceId(invoiceId); Boolean externalPayment = true; // Will use a external payment method List controlPluginNames = null; -Map pluginProperty = null; +Map NULL_PLUGIN_PROPERTIES = null; InvoicePayment result = invoiceApi.createInstantPayment(invoiceId, invoicePayment, externalPayment, - controlPluginNames, - pluginProperty, + controlPluginNames, + NULL_PLUGIN_PROPERTIES, requestOptions); ``` ```ruby -payment = KillBillClient::Model::InvoicePayment.new -payment.account_id = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0" +user = "demo" +reason = nil +comment = nil + +payment = KillBillClient::Model::InvoicePayment.new +payment.account_id = "a24a1b9f-9d0f-4311-ad05-feac80f7b177" +payment.target_invoice_id = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7" payment.purchased_amount = '50.0' external_payment = true -payment.create(external_payment, - user, - reason, - comment, +payment.create(external_payment, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() + +account_id = '04779ade-11f9-48d1-88a1-a63be84d1cb7' +invoice_id = '46ab72dc-8abf-4984-818b-cf1558c7ef4b' + body = InvoicePayment(account_id=account_id, purchased_amount=50.0, target_invoice_id=invoice_id) invoiceApi.create_instant_payment(invoice_id, body, - created_by, - api_key, - api_secret, - external_payment=True) + external_payment=True, + created_by='demo', + reason='reason', + comment='comment') ``` -**Request Body** +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); -An invoicePayment resource object, with at least the following attributes: accountId, and purchasedAmount. +const accountId = 'ceaa4c46-723e-4229-ba77-c8656572e8ea'; +const invoiceId = '80825f6b-dc95-46f9-8e7e-ac16bf658f81'; +const invoicePayment: InvoicePayment = {accountId: accountId, targetInvoiceId: invoiceId, purchasedAmount:100}; -**Query Parameters** +api.createInstantPayment(invoicePayment, invoiceId, 'created_by'); +```` -| Name | Type | Required | Default | Description | -| ---- | -----| -------- | ------- | ----------- | -| **externalPayment** | boolean | no | false | If true, the payment method should be defaulted to the (system provided) external payment method. | +````php +$apiInstance = $client->getInvoiceApi(); -**Response** +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; -If successful, returns a status code of 201 and an empty body. +$invoiceId = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7"; +$accountId = "a24a1b9f-9d0f-4311-ad05-feac80f7b177"; +$externalPayment = true; +$controlPluginName = array("controlPluginName_example"); +$pluginProperty = array("pluginProperty_example"); +$body = new InvoicePayment(); +$body -> setAccountId($accountId); +$body -> setTargetInvoiceId($invoiceId); +$body -> setPurchasedAmount(100); -### Retrieve payments associated with an invoice +$result = $apiInstance->createInstantPayment($body, $xKillbillCreatedBy, $invoiceId, $xKillbillReason, $xKillbillComment, $externalPayment, $controlPluginName, $pluginProperty); +```` -Retrieves a list of invoicePayment objects for payments associated with the invoice +**Request Body** + +An [InvoicePayment](invoice-payment.html#invoice-payment-resource) resource object, with at least the following attributes: accountId, and purchasedAmount. + +**Query Parameters** + +| Name | Type | Required | Default | Description | +|-----------------------|-------------------|----------|---------|---------------------------------------------------------------------------------------------------| +| **externalPayment** | boolean | no | false | If true, the payment method should be defaulted to the (system provided) external payment method. | +| **controlPluginName** | array of strings | no | omit | list of payment control plugin names. | +| **pluginProperty** | array of strings | no | omit | list of plugin properties, if any. Should be in the format `key%3Dvalue` | + +**Response** + +If successful, returns a status code of 201 and an empty body. + + +### Retrieve payments associated with an invoice + +Returns a list of [Invoice Payment](invoice-payment.html) objects corresponding to payments associated with the invoice. **HTTP Request** @@ -1905,10 +2486,10 @@ Boolean withPluginInfo = false; // Will not reflect plugin info Boolean withAttempts = false; // Will not reflect payment attempts InvoicePayments invoicePayments = invoiceApi.getPaymentsForInvoice(invoiceId, - withPluginInfo, - withAttempts, - AuditLevel.NONE, - inputOptions); + withPluginInfo, + withAttempts, + AuditLevel.NONE, + requestOptions); ``` ```ruby @@ -1917,10 +2498,31 @@ TODO ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '8291871e-b16e-45e6-a971-577d44727327' -invoiceApi.get_payments_for_invoice(invoice_id, api_key, api_secret) +invoice_id = '46ab72dc-8abf-4984-818b-cf1558c7ef4b' + +invoice_payments = invoiceApi.get_payments_for_invoice(invoice_id) ``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = '80825f6b-dc95-46f9-8e7e-ac16bf658f81'; + +const response: AxiosResponse = await api.getPaymentsForInvoice(invoiceId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7"; +$withPluginInfo = false; +$withAttempts = false; +$audit = "NONE"; + +$result = $apiInstance->getPaymentsForInvoice($invoiceId, $withPluginInfo, $withAttempts, $audit); +```` + > Example Response: ```json @@ -1969,9 +2571,7 @@ invoiceApi.get_payments_for_invoice(invoice_id, api_key, api_secret) | ---- | -----| -------- | ------- | ---- | | **withPluginInfo** | boolean | no | false | If true, plugin info is included | | **withAttempts** | boolean | no | false | If true, payment attempts are included | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| **audit** | string | no | "NONE" | Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL" | **Response** @@ -1984,6 +2584,8 @@ Custom fields are `{key, value}` attributes that can be attached to any customer ### Add custom fields to an invoice +Adds one or more custom fields to an invoice object. Existing custom fields are not disturbed. + **HTTP Request** `POST http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/customFields` @@ -2027,12 +2629,15 @@ invoiceApi.createInvoiceCustomFields(invoiceId, ``` ```ruby +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + custom_field = KillBillClient::Model::CustomFieldAttributes.new custom_field.object_type = 'INVOICE' custom_field.name = 'Test Custom Field' custom_field.value = 'test_value' -invoice.add_custom_field(custom_field, +invoice.add_custom_field(custom_field, user, reason, comment, @@ -2041,19 +2646,48 @@ invoice.add_custom_field(custom_field, ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac' + +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' body = CustomField(name='Test Custom Field', value='test_value') invoiceApi.create_invoice_custom_fields(invoice_id, [body], - created_by, - api_key, - api_secret) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const customField: CustomField = {name: "Test Custom Field", value: "test_value"}; +const customFields = [customField]; + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; + +api.createInvoiceCustomFields(customFields, invoiceIdId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; + +$customField = new CustomField(); +$customField -> setName('Test Custom Field'); +$customField -> setValue('test_value'); +$body = array($customField); + +$result = $apiInstance->createInvoiceCustomFields($body, $xKillbillCreatedBy, $invoiceId, $xKillbillReason, $xKillbillComment); +```` + **Request Body** -A list of [Custom Field](custom-field.html#custom-field-custom-field-resource) objects. Each object should specify at least the the `name` and `value` attribute. For example: +A list of [Custom Field](custom-field.html#custom-field-custom-field-resource) objects. Each object should specify at least the `name` and `value` attribute. For example: [ { "name": "CF1", "value": "123" } ] @@ -2097,18 +2731,40 @@ List customFields = invoiceApi.getInvoiceCustomFields(invoiceId, ``` ```ruby +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + audit = 'NONE' -invoice.custom_fields(audit, options) +custom_fields = invoice.custom_fields(audit, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac' -invoiceApi.get_invoice_custom_fields(invoice_id, api_key, api_secret) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' + +custom_fields = invoiceApi.get_invoice_custom_fields(invoice_id) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; +const audit = 'NONE'; + +const response: AxiosResponse = await api.getInvoiceCustomFields(invoiceIdId, audit, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; +$audit = "NONE"; + +$result = $apiInstance->getInvoiceCustomFields($invoiceId, $audit); +```` + > Example Response: ```json @@ -2156,8 +2812,8 @@ curl -v \ -H "X-Killbill-CreatedBy: demo" \ -H "X-Killbill-Reason: demo" \ -H "X-Killbill-Comment: demo" \ - -d '[ { "customFieldId": "349de10f-4bb1-4e1a-93f6-11b745200bf5", "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d", "objectType": "INVOICE", "name": "Test Custom Field", "value": "test_modify_value", "auditLogs": [] }]' \ - "http://127.0.0.1:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields" + -d '[ { "customFieldId": "9e0c4b85-c257-437c-ae9c-d32eac6f010c", "objectId": "7bf0f3d6-4ffb-4d5a-98c7-1158083432d0", "value": "new value" }]' \ + "http://127.0.0.1:8080/1.0/kb/invoices/7bf0f3d6-4ffb-4d5a-98c7-1158083432d0/customFields" ``` ```java @@ -2181,40 +2837,74 @@ invoiceApi.modifyInvoiceCustomFields(invoiceId, ``` ```ruby -custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9' -custom_field.name = 'Test Modify' -custom_field.value = 'test_modify_value' +user = "demo" +reason = nil +comment = nil -invoice.modify_custom_field(custom_field, - user, +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + +custom_field = KillBillClient::Model::CustomFieldAttributes.new +custom_field.custom_field_id = 'ec53d741-e52a-4860-a6d3-03bb22b24a90' +custom_field.value = 'new value' + +invoice.modify_custom_field(custom_field, + user, reason, - comment, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac' -custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9' -body = CustomField(custom_field_id=custom_field_id, - name='Test Custom Field', - value='test_value') -invoiceApi.modify_invoice_custom_fields(invoice_id, - [body], - created_by, - api_key, - api_secret) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' +custom_field_id = 'da4c9071-e3da-418c-aa28-2b7cbf9ec3c8' +body = CustomField(custom_field_id=custom_field_id, value='New Value') + +invoiceApi.modify_invoice_custom_fields(invoice_id, + [body], + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; + +const customField: CustomField = {customFieldId: "45ee24dd-cb1c-48a9-91a8-ecf5b76fd76b", value: "new_value"}; + const customFields = [customField]; + +api.modifyInvoiceCustomFields(customFields, invoiceIdId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; + +$customField = new CustomField(); +$customField -> setCustomFieldId('70749248-8bc5-4a98-9238-9eda7ed34d56'); +$customField -> setValue('new_value'); +$body = array($customField); + +$apiInstance->modifyInvoiceCustomFields($body, $xKillbillCreatedBy, $invoiceId, $xKillbillReason, $xKillbillComment); +```` + **Requst Body** -A list of [Custom Field](custom-field.html#custom-field-custom-field-resource) objects representing the fields to substitute for existing ones. Each object should specify at least the the `customFieldId` and `value` attribute. For example: +A list of [Custom Field](custom-field.html#custom-field-custom-field-resource) objects specifying the id and the new value for the custom fields to be modified. Each object should specify at least the `customFieldId` and `value` attribute. For example: [ { "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f", "value": "123" } ] - +Although the `fieldName` and `objectType` can be specified in the request body, these attributes cannot be modified, only the `value` can be modified. **Query Parameters** @@ -2227,7 +2917,7 @@ If successful, returns a status code of 204 and an empty body. ### Remove custom fields from invoice -Remove a specified set of custom fields from the invoice +Delete one or more custom fields from an invoice. It accepts query parameters corresponding to the custom field ids to be deleted. if no query parameters are specified, it deletes all the custom fields corresponding to the invoice. **HTTP Request** @@ -2263,25 +2953,60 @@ invoiceApi.deleteInvoiceCustomFields(invoiceId, ``` ```ruby -custom_field_id = custom_field.id +user = "demo" +reason = nil +comment = nil + +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + +custom_field_id = 'ec53d741-e52a-4860-a6d3-03bb22b24a90' -invoice.remove_custom_field(custom_field_id, - user, +invoice.remove_custom_field(custom_field_id, + user, reason, - comment, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac' -invoiceApi.delete_invoice_custom_fields(invoice_id, - created_by, - api_key, - api_secret) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' +custom_fields = ['da4c9071-e3da-418c-aa28-2b7cbf9ec3c8'] + +invoiceApi.delete_invoice_custom_fields(invoice_id=invoice_id, + custom_field=custom_fields, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; + +const customField = '45ee24dd-cb1c-48a9-91a8-ecf5b76fd76b'; +const customFields = [customField]; + +api.deleteInvoiceCustomFields(invoiceIdId, 'created_by', customFields); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; + +$customFields = array("70749248-8bc5-4a98-9238-9eda7ed34d56"); + +$apiInstance->deleteInvoiceCustomFields($invoiceId, $xKillbillCreatedBy, $customFields, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** | Name | Type | Required | Default | Description | @@ -2296,13 +3021,13 @@ If successful, returns a status code of 204 and an empty body. ## Tags -See [Account Tags](account.html#account-tags) for an introduction. +See [Tags](tag.html) for an introduction to tags. The only `system` tag applicable for an `Invoice` is `WRITTEN_OFF` (`00000000-0000-0000-0000-000000000004`), which as it's name indicates, is used to write off an unpaid invoice, bringing its balance to $0. ### Add tags to invoice -This API adds one or more tags to an invoice. The tag definitions must already exist. +This API adds one or more tags to an invoice. The [tag definition](#tag-definition) corresponding to the tag being added must already exist. **HTTP Request** @@ -2340,7 +3065,14 @@ Tags result = invoiceApi.createInvoiceTags(invoiceId, ``` ```ruby -tag_name = 'TEST' +user = "demo" +reason = nil +comment = nil + +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + +tag_name = 'WRITTEN_OFF' invoice.add_tag(tag_name, user, @@ -2351,16 +3083,39 @@ invoice.add_tag(tag_name, ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069' -tag = ["00000000-0000-0000-0000-000000000004"] -invoiceApi.create_invoice_tags(invoice_id, - tag, - created_by, - api_key, - api_secret) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' +tagDefIds = ["00000000-0000-0000-0000-000000000004"] + +invoiceApi.create_invoice_tags(invoice_id, + tagDefIds, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; +const tagDefIds = ['00000000-0000-0000-0000-000000000004']; + +api.createInvoiceTags(tagDefIds, invoiceIdId, 'created_by'); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; +$tagDefIds = array("00000000-0000-0000-0000-000000000004"); + +$result = $apiInstance->createInvoiceTags($tagDefIds, $xKillbillCreatedBy, $invoiceId, $xKillbillReason, $xKillbillComment); +```` + **Request Body** A JSON array containing one or more tag definition ids to be added as tags. @@ -2408,21 +3163,45 @@ List tags = invoiceApi.getInvoiceTags(invoiceId, ``` ```ruby +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + included_deleted = false audit = 'NONE' -invoice.tags(included_deleted, +tags = invoice.tags(included_deleted, audit, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '3e94fccf-0f37-40aa-90a4-122a4f381ebc' -invoiceApi.get_invoice_tags(invoice_id, api_key, api_secret) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' + +tags = invoiceApi.get_invoice_tags(invoice_id) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; +const includeDeleted = false; +const audit = 'NONE'; + +const response: AxiosResponse = await api.getInvoiceTags(invoiceIdId, includeDeleted, audit); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; +$includedDeleted = false; +$audit = "NONE"; + +$result = $apiInstance->getInvoiceTags($invoiceId, $includedDeleted, $audit); +```` + > Example Response: ```json @@ -2451,7 +3230,7 @@ If successful, returns a status code of 200 and a list of tag objects. ### Remove tags from invoice -Removes a list of tags attached to an invoice. +This API deletes one or more tags attached to an invoice. **HTTP Request** @@ -2485,7 +3264,14 @@ invoiceApi.deleteInvoiceTags(invoiceId, ``` ```ruby -tag_name = 'TEST' +user = "demo" +reason = nil +comment = nil + +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = '7bf0f3d6-4ffb-4d5a-98c7-1158083432d0' + +tag_name = 'WRITTEN_OFF' invoice.remove_tag(tag_name, user, @@ -2496,15 +3282,39 @@ invoice.remove_tag(tag_name, ```python invoiceApi = killbill.api.InvoiceApi() -invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069' -invoiceApi.delete_invoice_tags(invoice_id, - created_by, - api_key, - api_secret, - tag_def=tag) +invoice_id = 'b64bd7d2-167b-4e89-bb76-15ee955801f1' +tagDefIds = ['00000000-0000-0000-0000-000000000004'] + +invoiceApi.delete_invoice_tags(invoice_id, + tag_def=tagDefIds, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceIdId = '800ca6d0-8c33-458c-bf1a-4de22e960441'; +const tagDefIds = ['00000000-0000-0000-0000-000000000004']; + +api.deleteInvoiceTags(invoiceIdId, 'created_by', tagDefIds); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$invoiceId = "800ca6d0-8c33-458c-bf1a-4de22e960441"; +$tagDef = array("00000000-0000-0000-0000-000000000004"); + +$apiInstance->deleteInvoiceTags($invoiceId, $xKillbillCreatedBy, $tagDef, $xKillbillReason, $xKillbillComment); +```` + **Query Parameters** | Name | Type | Required | Default | Description | @@ -2517,13 +3327,14 @@ If successful, returns a status code of 204 and an empty body. ## Translation -These endpoints support translation of invoices to a different language when required by the customer. Refer to our [Internationalization manual](https://docs.killbill.io/latest/internationalization.html#_language_translations) for an introduction. +These endpoints support translation of invoices to a different language when required by the customer. Translation replaces words and phrases in an invoice or catalog with the equivalent words or phrases in a different language. A tenant may upload translation tables for specific locales (e.g., locale `fr_FR` for French). When a customer accesses an invoice, that invoice is generated from the system data, formatted using the appropriate [template](invoice.html#template), and translated according to the locale of the customer's account, if a translation table exists for that locale. -Translation replaces words and phrases in an invoice or catalog with the equivalent words or phrases in a different language. A tenant may upload translation tables for specific locales (e.g., locale `fr_FR` for French). When a customer accesses an invoice, that invoice will be generated from the system data, formatted using the appropriate template (see below), and translated according to the locale of the customer's account, if a translation table exists for that locale. +Refer to the [Invoice templates document](https://docs.killbill.io/latest/invoice_templates) and +[Internationalization manual](https://docs.killbill.io/latest/internationalization.html#_language_translations) for an introduction to the translation process/Kill Bill's internationalization support. ### Upload the catalog translation for the tenant -Uploads a catalog translation table that will be saved under a specified locale. The translation table gives a translation for specific names in the current catalog. +Uploads a catalog translation table that will be saved under a specified locale. The translation table provides a translation for specific names in the current catalog that may appear on an invoice (for example, plan names, product names, etc.). **HTTP Request** @@ -2532,6 +3343,7 @@ Uploads a catalog translation table that will be saved under a specified locale. > Example Request: ```shell +# specify the translations in the request body curl -v \ -X POST \ -u admin:password \ @@ -2545,9 +3357,24 @@ curl -v \ -d '"sports-monthly = Voiture Sport silver-monthly = plan d'argent mensuel"' \ "http://localhost:8080/1.0/kb/invoices/catalogTranslation/fr_FR" + +OR +# specify a properties file containing the translations +curl -v \ + -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H 'X-Killbill-CreatedBy: admin' \ + -H "Content-Type: text/plain" \ + -X POST \ + -d @CatalogTranslation_de_DE.properties \ + http://127.0.0.1:8080/1.0/kb/invoices/catalogTranslation/de_DE ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String locale = "en_US"; String body = "gold-monthly=plan"; Boolean deleteIfExists = true; @@ -2555,42 +3382,69 @@ invoiceApi.uploadCatalogTranslation(locale, body, deleteIfExists,requestOptions) ``` ```ruby +user = "demo" +reason = nil +comment = nil + catalog_translation = 'sports-monthly = Voiture Sport' locale = "fr_FR" -delete_if_exists = false - -KillBillClient::Model::Invoice.upload_catalog_translation(catalog_translation, - locale, - delete_if_exists, - user, - reason, - comment, +delete_if_exists = true + +KillBillClient::Model::Invoice.upload_catalog_translation(catalog_translation, + locale, + delete_if_exists, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() locale = 'fr_FR' -body = "sports-monthly = Voiture Sport" +body = 'sports-monthly = Voiture Sport' invoiceApi.upload_catalog_translation(locale, body, - created_by, - api_key, - api_secret) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const locale = 'fr_FR'; +const deleteIfExists = true; +const body = 'sports-monthly = Voiture Sport'; + +api.uploadCatalogTranslation(body, locale, 'created_by', deleteIfExists); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$body = "sports-monthly = Voiture Sport"; +$locale = "fr_FR"; +$deleteIfExists = true; + +$result = $apiInstance->uploadCatalogTranslation($body, $xKillbillCreatedBy, $locale, $xKillbillReason, $xKillbillComment, $deleteIfExists); +```` + **Request Body** A table of translation items. For example: gold-monthly = plan Or mensuel - silver-monthly = plan d'argent mensuel Note that this table does not use a special syntax such as JSON. The equals sign is the only punctuation. There are no brackets or quotation marks. -The names translated would be primarily plan names, product names, and other items that may appear on an invoice. +Alternatively, the path of a properties file containing the translations can also be specified as the request body. **Query Parameters** @@ -2600,7 +3454,7 @@ The names translated would be primarily plan names, product names, and other ite **Response** -If successful, returns a status code of 201 and a Location header which can be used to retrieve the catalog translation. +If successful, returns a status code of 201 and a Location header that can be used to retrieve the catalog translation for the locale. ### Retrieve the catalog translation for the tenant @@ -2622,23 +3476,41 @@ curl -v \ ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String locale = "en_US"; String translation = invoiceApi.getCatalogTranslation(locale, requestOptions); ``` ```ruby locale = "fr_FR" -KillBillClient::Model::Invoice.get_catalog_translation(locale, - options) +translations = KillBillClient::Model::Invoice.get_catalog_translation(locale, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() locale = 'fr_FR' -invoiceApi.get_catalog_translation(locale, api_key, api_secret) +translations = invoiceApi.get_catalog_translation(locale) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const locale = 'fr_FR'; + +const response: AxiosResponse = await api.getCatalogTranslation(locale); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$locale = "fr_FR"; + +$result = $apiInstance->getCatalogTranslation($locale); +```` + > Example Response: ```json @@ -2659,7 +3531,7 @@ If successful, returns a status code of 200 and the translation table. A status ### Upload the invoice translation for the tenant -Uploads an invoice translation table that will be saved under a specified locale. The translation table gives a translation for specific names in the corresponding invoice template. +Uploads an invoice translation table that will be saved under a specified locale. The translation table provides a translation for specific names in the corresponding invoice template (for example invoice title, invoice date, etc.). **HTTP Request** @@ -2668,6 +3540,7 @@ Uploads an invoice translation table that will be saved under a specified locale > Example Request: ```shell +# specify the translations in the request body curl -v \ -X POST \ -u admin:password \ @@ -2682,9 +3555,28 @@ curl -v \ invoiceDate=Date: invoiceNumber=Facture #" \ "http://localhost:8080/1.0/kb/invoices/translation/fr_FR" + +OR + +# specify a properties file containing the translations +curl -v \ + -X POST \ + -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H "Content-Type: text/plain" \ + -H "Accept: text/plain" \ + -H "X-Killbill-CreatedBy: demo" \ + -H "X-Killbill-Reason: demo" \ + -H "X-Killbill-Comment: demo" \ + --data-binary @InvoiceTranslation_de_DE.properties \ + "http://localhost:8080/1.0/kb/invoices/translation/de_DE?deleteIfExists=true" ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String locale = "en_US"; String body = "gold-monthly=plan"; Boolean deleteIfExists = true; @@ -2692,42 +3584,73 @@ String translation = invoiceApi.uploadInvoiceTranslation(locale, body, deleteIfE ``` ```ruby -invoice_translation = get_resource_as_string("InvoiceTranslation_fr_FR.properties") +user = "demo" +reason = nil +comment = nil + +invoice_translation = 'invoiceDate = date de facture' locale = "fr_FR" -delete_if_exists = false +delete_if_exists = true KillBillClient::Model::Invoice.upload_invoice_translation(invoice_translation, locale, - delete_if_exists, + delete_if_exists, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() locale = 'fr_FR' -body = "sports-monthly = Voiture Sport" +body = "invoiceDate = date de facture" +delete_if_exists = True invoiceApi.upload_invoice_translation(locale, body, - created_by, - api_key, - api_secret) + delete_if_exists=delete_if_exists, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const locale = 'fr_FR'; +const deleteIfExists = true; +const body = 'invoiceDate = date de facture'; + +api.uploadInvoiceTranslation(body, locale, 'created_by', deleteIfExists); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$body = "invoiceDate = date de facture"; +$locale = "fr_FR"; +$deleteIfExists = true; + +$result = $apiInstance->uploadInvoiceTranslation($body, $xKillbillCreatedBy, $locale, $xKillbillReason, $xKillbillComment, $deleteIfExists); +```` + **Request Body** A table of translation items. For example: invoiceTitle=FACTURE - invoiceDate=Date: - invoiceNumber=Facture # - invoiceAmount=Montant à payer Note that this table does not use a special syntax such as JSON. The equals sign is the only punctuation. There are no brackets or quotation marks. +Alternatively, the path of a properties file containing the translations can also be specified as the request body. **Query Parameters** @@ -2737,7 +3660,7 @@ Note that this table does not use a special syntax such as JSON. The equals sign **Response** -If successful, returns a status code of 201 and a Location header which can be used to retrieve the invoice translation. +If successful, returns a status code of 201 and a Location header that can be used to retrieve the invoice translations for the locale. ### Retrieve the invoice translation for the tenant @@ -2760,6 +3683,9 @@ curl -v \ ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String locale = "en_US"; String translation = invoiceApi.getInvoiceTranslation(locale, requestOptions); @@ -2767,17 +3693,32 @@ String translation = invoiceApi.getInvoiceTranslation(locale, requestOptions); ```ruby locale = "fr_FR" -KillBillClient::Model::Invoice.get_invoice_translation(locale, - options) +translations = KillBillClient::Model::Invoice.get_invoice_translation(locale,options) ``` ```python invoiceApi = killbill.api.InvoiceApi() locale = 'fr_FR' -invoiceApi.get_invoice_translation(locale, api_key, api_secret) +translations = invoiceApi.get_invoice_translation(locale) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const locale = 'fr_FR'; + +const response: AxiosResponse = await api.getInvoiceTranslation(locale); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$locale = "fr_FR"; + +$result = $apiInstance->getInvoiceTranslation($locale); +```` + > Example Response: ```text/plain @@ -2797,11 +3738,14 @@ If successful, returns a status code of 200 and the translation table. A status ## Template -A template is a document based on [**mustache**](https://mustache.github.io/) that provides the layout information for invoices. The template will be translated according to the translation table, if any, and the invoice data will be filled in by the Kill Bill system. Refer to our [Internationalization manual](https://docs.killbill.io/latest/internationalization.html#_language_translations) for an introduction. +A template is a document based on [**mustache**](https://mustache.github.io/) that provides the layout information for invoices. When a customer accesses an invoice, the invoice is generated from the system data, formatted using the appropriate template, and translated according to the [invoice translations](invoice.html#translation) corresponding to the locale of the customer's account if any. + +Refer to the [Invoice templates document](https://docs.killbill.io/latest/invoice_templates) and +[Internationalization manual](https://docs.killbill.io/latest/internationalization.html#_language_translations) for an introduction to the translation process/Kill Bill's internationalization support. ### Upload the manualPay invoice template for the tenant -Uploads an invoice template based on the manual pay option, for accounts that have the MANUAL_PAY tag. These accounts manually pay their invoices (e.g. ACH). Typically, this template will contain extra information like the company bank account details, PO number, etc. +Uploads an invoice template for accounts that have the MANUAL_PAY tag. These accounts manually pay their invoices (e.g. ACH). Typically, this template will contain extra information like the company bank account details, PO number, etc. **HTTP Request** @@ -2810,6 +3754,7 @@ Uploads an invoice template based on the manual pay option, for accounts that ha > Example Request: ```shell +# specify the template in the request body curl -v \ -X POST \ -u admin:password \ @@ -2821,10 +3766,26 @@ curl -v \ -H "X-Killbill-Reason: demo" \ -H "X-Killbill-Comment: demo" \ -d '"Some_HTML_String"' \ - "http://localhost:8080/1.0/kb/invoices/manualPayTemplate?deleteIfExists=false" + "http://localhost:8080/1.0/kb/invoices/manualPayTemplate" + +OR + +# specify the template in a separate mustache file +curl -v \ + -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H 'X-Killbill-CreatedBy: admin' \ + -H "Content-Type: text/html" \ + -X POST \ + -d @HTMLTemplate-manual-pay.mustache \ + "http://localhost:8080/1.0/kb/invoices/manualPayTemplate" ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String body = "Test HTML String"; Boolean deleteIfExists = true; String template = invoiceApi.uploadInvoiceMPTemplate(body, deleteIfExists,requestOptions); @@ -2832,15 +3793,19 @@ String template = invoiceApi.uploadInvoiceMPTemplate(body, deleteIfExists,reques ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_template = "Some_HTML_String" is_manual_pay = true -delete_if_exists = false -KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, - is_manual_pay, - delete_if_exists, - user, - reason, - comment, +delete_if_exists = true +KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, + is_manual_pay, + delete_if_exists, + user, + reason, + comment, options) ``` @@ -2849,14 +3814,36 @@ invoiceApi = killbill.api.InvoiceApi() body = 'Some_HTML_String' invoiceApi.upload_invoice_mp_template(body, - created_by, - api_key, - api_secret) + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const deleteIfExists = true; +const body = 'Some HTML String'; + +api.uploadInvoiceMPTemplate(body, 'created_by', deleteIfExists); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$body = "Some HTML String"; +$deleteIfExists = true; + +$result = $apiInstance->uploadInvoiceMPTemplate($body, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment, $deleteIfExists); +```` + **Request Body** -Contains a mustache manual pay template in HTML format. +Contains a mustache manual pay template in HTML format. Alternatively, the path of template file can also be specified as the request body. **Query Parameters** @@ -2867,7 +3854,7 @@ Contains a mustache manual pay template in HTML format. **Response** -If successful, returns a status code of 200 and an empty body. +If successful, returns a status code of 201 and a Location header that can be used to retrieve the manual payment invoice template. ### Retrieve the manualPay invoice template for the tenant @@ -2889,21 +3876,141 @@ curl -v \ ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String locale = "fr_FR"; String template = invoiceApi.getInvoiceMPTemplate(locale, requestOptions); ``` ```ruby +locale = "fr_FR" is_manual_pay = true -KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay, - options) +template = KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay, locale, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() +locale = 'fr_FR' -invoiceApi.get_invoice_mp_template(api_key, api_secret) +template = invoiceApi.get_invoice_mp_template(locale) +``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const locale = 'fr_FR'; + +const response: AxiosResponse = await api.getInvoiceMPTemplate(locale); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$locale = "fr_FR"; + +$result = $apiInstance->getInvoiceMPTemplate($locale); +```` + +> Example Response: + +```text/plain + + + + + +

{{text.invoiceTitle}}

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Insert image here + + +
+ {{text.invoiceDate}}{{invoice.formattedInvoiceDate}}
+ {{text.invoiceNumber}}{{invoice.invoiceNumber}}
{{text.companyName}}{{text.accountOwnerName}}{{account.name}}
{{text.companyAddress}} + + {{account.email}}
{{text.companyCityProvincePostalCode}} + + {{account.phone}}
{{text.companyCountry}} + + +
<{{text.companyUrl}} + + +
+
+
+
+ + + + {{#invoice.invoiceItems}} + + + + + + + {{/invoice.invoiceItems}} + + + + + + + + + + + + + + +
{{text.invoiceItemBundleName}} + {{text.invoiceItemDescription}} + {{text.invoiceItemServicePeriod}} + {{text.invoiceItemAmount}} +
{{description}}{{planName}}{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}{{invoice.currency}} {{amount}}
+
+ {{text.invoiceAmount}}{{invoice.chargedAmount}}
+ {{text.invoiceAmountPaid}}{{invoice.paidAmount}}
+ {{text.invoiceBalance}}{{invoice.balance}}
+ + ``` **Query Parameters** @@ -2917,7 +4024,7 @@ If successful, returns a status code of 201 and the manual pay template. ### Upload the invoice template for the tenant -Uploads an invoice template based on an automatic payment method. This is appropriate for accounts without the MANUAL_PAY tag. +Uploads an invoice template for accounts with an automatic payment method (accounts without the `MANUAL_PAY` tag). **HTTP Request** @@ -2927,6 +4034,7 @@ Uploads an invoice template based on an automatic payment method. This is approp > Example Request: ```shell +# specify the template in the request body curl -v \ -X POST \ -u admin:password \ @@ -2939,41 +4047,88 @@ curl -v \ -H "X-Killbill-Comment: demo" \ -d "Some_HTML_String" \ "http://localhost:8080/1.0/kb/invoices/template" + +OR + +# specify the template in a separate mustache file +curl -v \ + -X POST \ + -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H "Content-Type: text/html" \ + -H "Accept: text/html" \ + -H "X-Killbill-CreatedBy: demo" \ + -H "X-Killbill-Reason: demo" \ + -H "X-Killbill-Comment: demo" \ + -d @HTMLTemplate.mustache \ + "http://localhost:8080/1.0/kb/invoices/template?deleteIfExists=true" ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String body = "Test HTML String"; Boolean deleteIfExists = true; String template = invoiceApi.uploadInvoiceTemplate(body, deleteIfExists,requestOptions); ``` ```ruby +user = "demo" +reason = nil +comment = nil + invoice_template = "Some_HTML_String" is_manual_pay = false -delete_if_exists = false -KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, - is_manual_pay, - delete_if_exists, - user, - reason, - comment, +delete_if_exists = true +KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, + is_manual_pay, + delete_if_exists, + user, + reason, + comment, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() body = 'Some_HTML_String' +delete_if_exists = True invoiceApi.upload_invoice_template(body, - created_by, - api_key, - api_secret) + delete_if_exists=delete_if_exists, + created_by='demo', + reason='reason', + comment='comment') ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const deleteIfExists = true; +const body = 'Some HTML String'; + +api.uploadInvoiceTemplate(body, 'created_by', deleteIfExists); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$xKillbillCreatedBy = "user"; +$xKillbillReason = "reason"; +$xKillbillComment = "comment"; + +$body = "Some HTML String"; +$deleteIfExists = true; + +$result = $apiInstance->uploadInvoiceTemplate($body, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment, $deleteIfExists); +```` + **Request Body** -Contains a mustache automatic pay template in HTML format. +Contains a mustache automatic pay template in HTML format. Alternatively, the path of template file can also be specified as the request body. **Query Parameters** @@ -2984,7 +4139,7 @@ Contains a mustache automatic pay template in HTML format. **Response** -If successful, returns a status code of 200 and an empty body. +If successful, returns a status code of 201 and a Location header that can be used to retrieve the automatic payment invoice template. ### Retrieve the invoice template for the tenant @@ -3007,20 +4162,135 @@ curl -v \ ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + String template = invoiceApi.getInvoiceTemplate(requestOptions); ``` ```ruby +locale = "fr_FR" is_manual_pay = false -KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay, - options) +template = KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay, locale, options) ``` ```python invoiceApi = killbill.api.InvoiceApi() -invoiceApi.get_invoice_template(api_key, api_secret) +template = invoiceApi.get_invoice_template() +``` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const response: AxiosResponse = await api.getInvoiceTemplate(); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$result = $apiInstance->getInvoiceTemplate(); +```` + +> Example Response: + +```text/plain + + + + + +

{{text.invoiceTitle}}

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Insert image here + + +
+ {{text.invoiceDate}}{{invoice.formattedInvoiceDate}}
+ {{text.invoiceNumber}}{{invoice.invoiceNumber}}
{{text.companyName}}{{text.accountOwnerName}}{{account.name}}
{{text.companyAddress}} + + {{account.email}}
{{text.companyCityProvincePostalCode}} + + {{account.phone}}
{{text.companyCountry}} + + +
<{{text.companyUrl}} + + +
+
+
+
+ + + + {{#invoice.invoiceItems}} + + + + + + + {{/invoice.invoiceItems}} + + + + + + + + + + + + + + +
{{text.invoiceItemBundleName}} + {{text.invoiceItemDescription}} + {{text.invoiceItemServicePeriod}} + {{text.invoiceItemAmount}} +
{{description}}{{planName}}{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}{{invoice.currency}} {{amount}}
+
+ {{text.invoiceAmount}}{{invoice.chargedAmount}}
+ {{text.invoiceAmountPaid}}{{invoice.paidAmount}}
+ {{text.invoiceBalance}}{{invoice.balance}}
+ + ``` @@ -3040,20 +4310,20 @@ The translation and templating process may seem a little complex. Here is a simp 2. Suppose the tenant does business with German customers. She then should upload translation tables, perhaps provided by customers, designated for the German locale (de_DE). Tables are needed for both invoice items and catalog items. The invoice items to be translated are the names of the fields on the template, such as invoiceTitle, invoiceAmount, etc. The catalog items to be translated are the names for actual items such as product name and plan name. There can be translation tables for any number of distinct locales. -Catalog translation example (German): + Catalog translation example (German): gold plan = Goldplan sports car = Sportwagen -Invoice transaltion example (German): + Invoice translation example (German): invoiceTitle = Rechnung invoiceNumber = Rechnungsnumber invoiceBalance = Rechnungssaldo -3. Each account has a designated locale. When an invoice is retrieved for an account, the appropriate translation tables, if any, are used to translate the invoice. +3. Each account has a designated locale. When an invoice is retrieved for an account, the invoice is generated using the invoice template and the appropriate translation tables, if any. -You can refer to the (Invoice Templates Tutorial)[https://docs.killbill.io/latest/invoice_templates.html] to know more about the how this works. +Refer to the [Invoice Templates Tutorial](https://docs.killbill.io/latest/invoice_templates.html) for a step-by-step tutorial. ## Audit Logs @@ -3063,7 +4333,15 @@ Audit logs provide a record of events that occur involving various specific reso ### Retrieve invoice audit logs with history by invoice id -Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice. History information is included with each record. +Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice. History information (a copy of the full invoice object) is included with each record. + +Some examples: +* Assuming the API is invoked after an invoice is generated, it would return one record: + * An `INSERT` record corresponding to the invoice creation +* Assuming the API is invoked after an invoice is voided, it would return two records: + * An `INSERT` record corresponding to the invoice creation + * An `UPDATE` record corresponding to the invoice status update + **HTTP Request** @@ -3082,11 +4360,44 @@ curl \ ``` ```java +import org.killbill.billing.client.api.gen.InvoiceApi; +protected InvoiceApi invoiceApi; + UUID invoiceId = UUID.fromString("8f6f3405-249f-4b66-a0c2-ee84e884e81d"); AuditLogs logs = invoiceApi.getInvoiceAuditLogsWithHistory(invoiceId, requestOptions); - ``` +````ruby +invoice = KillBillClient::Model::Invoice.new +invoice.invoice_id = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7" + +audit_logs = invoice.audit_logs_with_history(options) +```` + +````python +invoiceApi = killbill.api.InvoiceApi() + +invoice_id = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7" + +audit_logs = invoiceApi.get_invoice_audit_logs_with_history(invoice_id) +```` + +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const invoiceId = 'bb9cf385-cc78-46a6-b069-924bdfdeb4f7'; + +const response: AxiosResponse = await api.getInvoiceAuditLogsWithHistory(invoiceId); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$invoiceId = "bb9cf385-cc78-46a6-b069-924bdfdeb4f7"; + +$result = $apiInstance->getInvoiceAuditLogsWithHistory($invoiceId); +```` + > Example Response: ```json @@ -3138,7 +4449,14 @@ If successful, returns a status code of 200 and a list of audit logs with histor ### Retrieve invoice item audit logs with history by invoice item id -Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice item. History information is included with each record. +Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice item. History information (a copy of the full invoice item object) is included with each record. + +Some examples: +Assuming this API is invoked with an invoice item id as soon as the invoice is generated, it would return: + * An `INSERT` record corresponding to the invoice item creation +* Assuming a CBA_ADJ invoice item is deleted, and this API is invoked with the CBA_ADJ invoice item id, this API would return two records: + * An `INSERT` record corresponding to the invoice item creation + * An `UPDATE` record corresponding to the invoice item deletion **HTTP Request** @@ -3154,6 +4472,46 @@ curl \ -H "Accept: application/json" \ "http://127.0.0.1:8080/1.0/kb/invoiceItems/b45ef2ac-e4b7-4e79-89d8-1c2e95838300/auditLogsWithHistory" ``` + +````java +import org.killbill.billing.client.api.gen.InvoiceItemApi; +protected InvoiceItemApi invoiceItemApi; + +UUID invoiceItemId = UUID.fromString("57f4f41d-81a2-4521-8420-c241ecc90a80"); +AuditLogs logs = invoiceItemApi.getInvoiceItemAuditLogsWithHistory(invoiceItemId, requestOptions); +```` + +````ruby +invoice_item = KillBillClient::Model::InvoiceItem.new +invoice_item.invoice_item_id = "6f3d5bd3-f8b3-4615-9940-5a15a5060fb5" + +audit_logs = invoice_item.audit_logs_with_history(options) +```` + +````python +invoiceItemApi = killbill.api.InvoiceItemApi() + +invoice_item_id = "6f3d5bd3-f8b3-4615-9940-5a15a5060fb5" + +audit_logs = invoiceItemApi.get_invoice_item_audit_logs_with_history(invoice_item_id) +```` + +````javascript +const api: killbill.InvoiceItemApi = new killbill.InvoiceItemApi(config); + +const invoiceItemId = '6f3d5bd3-f8b3-4615-9940-5a15a5060fb5'; + +const response: AxiosResponse = await api.getInvoiceItemAuditLogsWithHistory(invoiceItemId); +```` + +````php +$apiInstance = $client->getInvoiceItemApi(); + +$invoiceItemId = "6f3d5bd3-f8b3-4615-9940-5a15a5060fb5"; + +$result = $apiInstance->getInvoiceItemAuditLogsWithHistory($invoiceItemId); +```` + > Example Response: ```json @@ -3208,106 +4566,6 @@ None. If successful, returns a status code of 200 and a list of audit logs with history. - - -### Retrieve invoice payment audit logs with history by invoice payment id - -Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice payment. History information is included with each record. - - - -**HTTP Request** - -`GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{invoicePaymentId}/auditLogsWithHistory` - -> Example Request: - -```shell -curl \ - -u admin:password \ - -H "X-Killbill-ApiKey: bob" \ - -H "X-Killbill-ApiSecret: lazar" \ - -H "Accept: application/json" \ - "http://127.0.0.1:8080/1.0/kb/invoicePayments/5eedf918-b418-4d14-8dba-51c977a3f700/auditLogsWithHistory" -``` -> Example Response: - -```json -[ - { - "changeType": "INSERT", - "changeDate": "2019-02-22T23:23:21.000Z", - "objectType": "INVOICE_PAYMENT", - "objectId": "5eedf918-b418-4d14-8dba-51c977a3f700", - "changedBy": "admin", - "reasonCode": null, - "comments": null, - "userToken": "39b3f8a2-d782-41cd-adcd-460b5f560192", - "history": { - "id": null, - "createdDate": "2019-02-22T23:23:21.000Z", - "updatedDate": null, - "recordId": 219, - "accountRecordId": 10, - "tenantRecordId": 1, - "type": "ATTEMPT", - "invoiceId": "d456a9b3-7e48-4f56-b387-1d65a492e75e", - "paymentId": null, - "paymentDate": "2019-02-22T23:23:21.000Z", - "amount": 10, - "currency": "USD", - "processedCurrency": "USD", - "paymentCookieId": "4d83dd1b-b053-4a4d-99de-9a9e6e0405af", - "linkedInvoicePaymentId": null, - "success": false, - "tableName": "INVOICE_PAYMENTS", - "historyTableName": "INVOICE_PAYMENT_HISTORY" - } - }, - { - "changeType": "UPDATE", - "changeDate": "2019-02-22T23:23:21.000Z", - "objectType": "INVOICE_PAYMENT", - "objectId": "5eedf918-b418-4d14-8dba-51c977a3f700", - "changedBy": "admin", - "reasonCode": null, - "comments": null, - "userToken": "39b3f8a2-d782-41cd-adcd-460b5f560192", - "history": { - "id": null, - "createdDate": "2019-02-22T23:23:21.000Z", - "updatedDate": null, - "recordId": 219, - "accountRecordId": 10, - "tenantRecordId": 1, - "type": "ATTEMPT", - "invoiceId": "d456a9b3-7e48-4f56-b387-1d65a492e75e", - "paymentId": "3ac3de91-0d94-463d-8286-8060846f229d", - "paymentDate": "2019-02-22T23:23:21.000Z", - "amount": 10, - "currency": "USD", - "processedCurrency": "USD", - "paymentCookieId": "4d83dd1b-b053-4a4d-99de-9a9e6e0405af", - "linkedInvoicePaymentId": null, - "success": true, - "tableName": "INVOICE_PAYMENTS", - "historyTableName": "INVOICE_PAYMENT_HISTORY" - } - } -] -``` - -**Query Parameters** - -None. - -**Response** - -If successful, returns a status code of 200 and a list of audit logs with history. - - - - ## List and Search These endpoints allow you to list all invoices or to search for a specific invoice. Note that these endpoints return shallow objects and thus the value `0` is returned for the `amount`, `creditAdj`, `refundAdj` and `balance` fields. In order to retrieve the actual data for these fields, additional endpoints (like retrieve invoice by id) would need to be invoked. @@ -3348,7 +4606,7 @@ Invoices result = invoiceApi.getInvoices(offset, offset = 0 limit = 100 -invoice.find_in_batches(offset, +invoices = KillBillClient::Model::Invoice.find_in_batches(offset, limit, options) ``` @@ -3356,9 +4614,25 @@ invoice.find_in_batches(offset, ```python invoiceApi = killbill.api.InvoiceApi() -invoiceApi.get_invoices(api_key, api_secret) +invoices = invoiceApi.get_invoices() ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const response: AxiosResponse = await api.getInvoices(); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$offset = 0; +$limit = 10; +$audit = "NONE"; + +$result = $apiInstance->getInvoices($offset, $limit, $audit); +```` + > Example Response: ```json @@ -3523,7 +4797,7 @@ If successful, returns a status code of 200 and a list of all invoices for this Search for an invoice by a specified search string. If the search string is a number, it is compared to the `invoiceNumber` attribute. An exact match is required. Otherwise, it is compared to the following attributes: `invoiceId`, `accountId`, or `currency`. The operation returns all invoice records in which the search string matches all or part of any one of these attributes. -**HTTP Request** +**HTTP Request** `GET http://127.0.0.1:8080/1.0/kb/invoices/search/{searchKey}` @@ -3547,7 +4821,7 @@ String searchKey = "1a49101b-305e-4b4d-8403-7377596407b6"; Long offset = 0L; Long limit = 1L; -invoiceApi.searchInvoices(searchKey, +Invoices result = invoiceApi.searchInvoices(searchKey, offset, limit, AuditLevel.NONE, @@ -3555,11 +4829,11 @@ invoiceApi.searchInvoices(searchKey, ``` ```ruby -search_key = 'COMMITTED' +search_key = '3135' offset = 0 limit = 100 -invoice.find_in_batches_by_search_key(search_key, +invoices = KillBillClient::Model::Invoice.find_in_batches_by_search_key(search_key, offset, limit, options) @@ -3569,9 +4843,28 @@ invoice.find_in_batches_by_search_key(search_key, invoiceApi = killbill.api.InvoiceApi() search_key = 'USD' -invoiceApi.search_invoices(search_key, api_key, api_secret) +invoices = invoiceApi.search_invoices(search_key) ``` +````javascript +const api: killbill.InvoiceApi = new killbill.InvoiceApi(config); + +const searchKey = '8600'; + +const response: AxiosResponse = await api.searchInvoices(searchKey); +```` + +````php +$apiInstance = $client->getInvoiceApi(); + +$searchKey = "8600"; //invoice number +$offset = 0; +$limit = 1; +$audit = "NONE"; + +$result = $apiInstance->searchInvoices($searchKey, $offset, $limit, $audit); +```` + > Example Response: ```json @@ -3606,12 +4899,10 @@ invoiceApi.search_invoices(search_key, api_key, api_secret) | **searchKey** | string | yes | none | What you want to find | | **offset** | long | none | 0 | Starting index for items listed | | **limit** | long | none | 100 | Maximum number of items to return on this page | -| **audit** | string | no | "NONE" | Level of audit information to return | - -Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL". +| **audit** | string | no | "NONE" | Level of audit information to return: "NONE", "MINIMAL" (only inserts), or "FULL" | **Response** -If successful, returns a list of all invoices matched with the search key entered. +If successful, returns a list of invoices matched with the specified search key.