From 46c7a14ccbb726bb5798ba1e2860451774b58d5d Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Mon, 16 Oct 2023 12:57:13 +0530 Subject: [PATCH] More corrections to subscription and invoice --- source/includes/_invoice.md | 4 +- source/includes/_subscription.md | 82 ++++++++++++++++++++------------ 2 files changed, 54 insertions(+), 32 deletions(-) diff --git a/source/includes/_invoice.md b/source/includes/_invoice.md index cfb4866..ecb5ae8 100644 --- a/source/includes/_invoice.md +++ b/source/includes/_invoice.md @@ -2926,7 +2926,7 @@ If successful, returns a status code of 204 and an empty body. ### Remove custom fields from 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. +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** @@ -3020,7 +3020,7 @@ $apiInstance->deleteInvoiceCustomFields($invoiceId, $xKillbillCreatedBy, $custom | Name | Type | Required | Default | Description | | ---- | -----| -------- | ------- | ----------- | -| **customField** | string | yes | none | Custom field object ID that should be deleted. Multiple custom fields can be deleted by specifying a separate **customField** parameter corresponding to each field | +| **customField** | string | yes | none | Custom field ID that should be deleted. Multiple custom fields can be deleted by specifying a separate **customField** parameter corresponding to each field | **Response** diff --git a/source/includes/_subscription.md b/source/includes/_subscription.md index 6ed137e..65b0a40 100644 --- a/source/includes/_subscription.md +++ b/source/includes/_subscription.md @@ -15,31 +15,32 @@ Please refer to our [subscription manual](http://docs.killbill.io/latest/usergui The `Subscription` resource represents a subscription. The attributes contained in the subscription resource are the following: -| Name | Type | Generated by | Description | -| ---- | -----| -------- | ------------ | -| **accountId** | string | system | UUID for the account | -| **bundleId** | string | system | UUID for the bundle | -| **subscriptionId** | string | system | UUID for this subscription | -| **externalKey** | string | user | Optional external key for the subscription | -| **bundleExternalKey** | string | user | Optional external key for the bundle | -| **startDate** | date | user | Datetime the service (entitlement) starts | -| **productName** | string | user | Name of the product subscribed (from catalog) | -| **productCategory** |string | user | Product catgory (see notes below) | -| **billingPeriod** | string | user | Billing period (see notes below) | -| **phaseType** | string | user | Type of the current plan phase (see notes below) | -| **priceList** | string | user | Name of the current price list (from catalog) | -| **planName** | string | user | Name of the current plan (from catalog) | -| **state** | string | system | Current state of the subscription (see notes below) | -| **sourceType** | string | system | Kind of subscription (see notes below) | -| **cancelledDate** | date | user | Datetime when the service stopped, or will stop | -| **chargedThroughDate** | date | system | Date up to which the subscription has been invoiced (see notes below) | -| **billingStartDate** | date | user | Datetime on which the system starts invoicing | -| **billingEndDate** | date | user | Datetime on which the system ends invoicing | -| **billCycleDayLocal** | integer | user or system | Day of the month on which invoices are generated, if applicable (see notes below) | -| **events** | list | system | list of subscription events tracking what happened (see notes below) | -| **prices** | list | user | list of prices, one for each phase in the plan | -| **priceOverrides** | list | user | list of prices if this subscription has price overrides (see notes below) | -| **quantity** | integer | user | quantity of subscriptions (see notes below) | +| Name | Type | Generated by | Description | +| ---- | -----| -------- |-------------------------------------------------------------------------------------------------------| +| **accountId** | string | system | UUID for the account | +| **bundleId** | string | system | UUID for the bundle | +| **subscriptionId** | string | system | UUID for this subscription | +| **externalKey** | string | user | Optional external key for the subscription | +| **bundleExternalKey** | string | user | Optional external key for the bundle | +| **startDate** | date | user | Datetime the service (entitlement) starts | +| **productName** | string | user | Name of the product subscribed (from catalog) | +| **productCategory** |string | user | Product catgory (see notes below) | +| **billingPeriod** | string | user | Billing period (see notes below) | +| **phaseType** | string | user | Type of the current plan phase (see notes below) | +| **priceList** | string | user | Name of the current price list (from catalog) | +| **planName** | string | user | Name of the current plan (from catalog) | +| **state** | string | system | Current state of the subscription (see notes below) | +| **sourceType** | string | system | Kind of subscription (see notes below) | +| **cancelledDate** | date | user | Datetime when the service stopped, or will stop | +| **chargedThroughDate** | date | system | Date up to which the subscription has been invoiced (see notes below) | +| **billingStartDate** | date | user | Datetime on which the system starts invoicing | +| **billingEndDate** | date | user | Datetime on which the system ends invoicing | +| **billCycleDayLocal** | integer | user or system | Day of the month on which invoices are generated, if applicable (see notes below) | +| **events** | list | system | List of subscription events corresponding to this subscription. See SubscriptionEvent resource below. | +| **prices** | list | user | list of prices, one for each phase in the plan | +| **priceOverrides** | list | user | list of prices if this subscription has price overrides (see notes below) | +| **quantity** | integer | user | quantity of subscriptions (see notes below) | +| **auditlogs** | array | system | Array of audit log records for this invoice | **productCategory**: possible values are BASE, ADD_ON, or STANDALONE @@ -58,7 +59,7 @@ The `Subscription` resource represents a subscription. The attributes contained **sourceType**: possible values are NATIVE, MIGRATED, or TRANSFERRED -**`chargedThroughDate`**: The date up to which the entitlement for this subscription has been invoiced. For `IN_ADVANCE` billing mode, this date will often be in the future; for `IN_ARREAR`, this date will often be in the past. For example, +**chargedThroughDate**: The date up to which the entitlement for this subscription has been invoiced. For `IN_ADVANCE` billing mode, this date will often be in the future; for `IN_ARREAR`, this date will often be in the past. For example, 1. A subscription is billed each month, on the 15th, in advance. If we check on May 31, the `chargedThroughDate` will be June 15th, 15 days ahead. If the subscription is ended on May 31, a prorated credit will need to be issued. @@ -66,12 +67,10 @@ The `Subscription` resource represents a subscription. The attributes contained These use cases assume that invoicing is up to date. If AUTO_INVOICING_OFF is set, invoicing relies on a manual process and may be late. In that situation the first use case may require a smaller credit or none at all, while the second case will have a larger amount to be billed to close out the subscription. -**`billCycleDayLocal`**: this value is either the overridden subscription billCycleDay (in case of BCD change) or the value at the subscription, bundle or account level (depending on the catalog [billing alignments](http://docs.killbill.io/latest/userguide_subscription.html#_billing_alignment_rules)). For `ACCOUNT` billing alignments, if the account level billCycleDay hasn't been set yet, the value returned would be null. +**billCycleDayLocal**: this value is either the overridden subscription billCycleDay (in case of BCD change) or the value at the subscription, bundle or account level (depending on the catalog [billing alignments](http://docs.killbill.io/latest/userguide_subscription.html#_billing_alignment_rules)). For `ACCOUNT` billing alignments, if the account level billCycleDay hasn't been set yet, the value returned would be null. -**`Events`**: possible event types are START_ENTITLEMENT, START_BILLING, PAUSE_ENTITLEMENT, PAUSE_BILLING, RESUME_ENTITLEMENT, RESUME_BILLING, PHASE, CHANGE, STOP_ENTITLEMENT, STOP_BILLING, SERVICE_STATE_CHANGE - -**`priceOverrides`**: List of overridden prices for specific plan phases. Can be specified to override the fixed/recurring price in the catalog for a particular phase. For example, suppose you are creating a subscription corresponding to a plan that has an `EVERGREEN` phase with a recurring price of `$100`. You can specify an overridden price of `200` while creating the subscription by specifying a `priceOverrides` object as follows: +**priceOverrides**: List of overridden prices for specific plan phases. Can be specified to override the fixed/recurring price in the catalog for a particular phase. For example, suppose you are creating a subscription corresponding to a plan that has an `EVERGREEN` phase with a recurring price of `$100`. You can specify an overridden price of `200` while creating the subscription by specifying a `priceOverrides` object as follows: ` @@ -87,6 +86,29 @@ These use cases assume that invoicing is up to date. If AUTO_INVOICING_OFF is se **quantity**: An integer value that specifies the quantity of subscription. The default value is 1. The corresponding invoice is generated as per the quantity. So if `price=$20/mo`, `quantity=$2` => `invoiceItem recurring amount=$40`. +## SubscriptionEvent Resource + +The SubscriptionEvent resource represents an event on a subscription. An event is generated when a subscription is created, cancelled, paused, resumed,etc. In addition, events are also generated when there is a phase change or plan change. + +| Name | Type | Generated by | Description | +|--------------------------|----------|--------------|-----------------------------------------------------------------------| +| **eventId** | string | system | UUID for this subscription event | +| **billingPeriod** | string | user | Billing period (see notes above) | +| **effectiveDate** | DateTime | system | DateTime that the event is effective | +| **catalogEffectiveDate** | DateTime | user | The effective date of the underlying catalog. | +| **plan** | string | user | Name of the current plan (from catalog) | +| **product** | date | user | Name of the product subscribed (from catalog) | +| **priceList** | string | user | Name of the current price list (from catalog) | +| **phase** | string | user | Name of the current phase (from catalog) | +| **eventType** | string | user | Type of event (see notes below) | +| **isBlockedBilling** | boolean | user | Boolean flag that indicates whether billing should be blocked | +| **isBlockedEntitlement** | boolean | user | Boolean flag that indicates whether the entitlement should be blocked | +| **serviceName** | string | user | Name of the service that inserts the event | +| **serviceStateName** | string | user | Name of the event state | + | + +**eventType**: possible event types are START_ENTITLEMENT, START_BILLING, PAUSE_ENTITLEMENT, PAUSE_BILLING, RESUME_ENTITLEMENT, RESUME_BILLING, PHASE, CHANGE, STOP_ENTITLEMENT, STOP_BILLING, SERVICE_STATE_CHANGE. See also [SubscriptionEventType](https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/entitlement/api/SubscriptionEventType.java). + ## Subscriptions These endpoints support the basic CRUD operations on Subscriptions.