Skip to content

Commit

Permalink
More corrections to subscription and invoice
Browse files Browse the repository at this point in the history
  • Loading branch information
@reshmabidikar
reshmabidikar committed Oct 16, 2023
1 parent b984924 commit 46c7a14
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 32 deletions.
4 changes: 2 additions & 2 deletions source/includes/_invoice.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down Expand Up @@ -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**

Expand Down
82 changes: 52 additions & 30 deletions source/includes/_subscription.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -58,20 +59,18 @@ 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.

2. A subscription is billed quarterly, in arrears, on the 10th of Feb., May, Aug., and Nov. If we check on Jul. 20, the `chargedThroughDate` will be May 10, over 2 months earlier. If the subscription is cancelled on Jul. 20, an additional invoice will need to be issued.

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:


`
Expand All @@ -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.
Expand Down

0 comments on commit 46c7a14

Please sign in to comment.