Merge pull request #138 from recurly/v3-v2019-10-10

Latest Changes for 2019-10-10 (usage, measured units, etc)

lib/recurly/resources/AddOn.js

@@ -13,6 +13,7 @@ const Resource = require('../Resource')
  * AddOn
  * @typedef {Object} AddOn
  * @prop {string} accountingCode - Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code.
+ * @prop {string} addOnType - Whether the add-on type is fixed, or usage-based.
  * @prop {string} code - The unique identifier for the add-on within its plan.
  * @prop {Date} createdAt - Created at
  * @prop {Array.<AddOnPricing>} currencies - Add-on pricing
@@ -22,6 +23,7 @@ const Resource = require('../Resource')
  * @prop {string} externalSku - Optional, stock keeping unit to link the item to other inventory systems.
  * @prop {string} id - Add-on ID
  * @prop {ItemMini} item - Just the important parts.
+ * @prop {string} measuredUnitId - System-generated unique identifier for an measured unit associated with the add-on.
  * @prop {string} name - Describes your add-on and will appear in subscribers' invoices.
  * @prop {string} object - Object type
  * @prop {boolean} optional - Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API.
@@ -32,11 +34,14 @@ const Resource = require('../Resource')
  * @prop {string} tierType - The type of tiering used by the Add-on.
  * @prop {Array.<Tier>} tiers - Tiers
  * @prop {Date} updatedAt - Last updated at
+ * @prop {number} usagePercentage - The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.
+ * @prop {string} usageType - Type of usage, returns usage type if `add_on_type` is `usage`.
  */
 class AddOn extends Resource {
   static getSchema () {
     return {
       accountingCode: String,
+      addOnType: String,
       code: String,
       createdAt: Date,
       currencies: ['AddOnPricing'],
@@ -46,6 +51,7 @@ class AddOn extends Resource {
       externalSku: String,
       id: String,
       item: 'ItemMini',
+      measuredUnitId: String,
       name: String,
       object: String,
       optional: Boolean,
@@ -55,7 +61,9 @@ class AddOn extends Resource {
       taxCode: String,
       tierType: String,
       tiers: ['Tier'],
-      updatedAt: Date
+      updatedAt: Date,
+      usagePercentage: Number,
+      usageType: String
     }
   }
 }

lib/recurly/resources/AddOnMini.js

@@ -13,23 +13,31 @@ const Resource = require('../Resource')
  * AddOnMini
  * @typedef {Object} AddOnMini
  * @prop {string} accountingCode - Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code.
+ * @prop {string} addOnType - Whether the add-on type is fixed, or usage-based.
  * @prop {string} code - The unique identifier for the add-on within its plan.
  * @prop {string} externalSku - Optional, stock keeping unit to link the item to other inventory systems.
  * @prop {string} id - Add-on ID
  * @prop {string} itemId - Item ID
+ * @prop {string} measuredUnitId - System-generated unique identifier for an measured unit associated with the add-on.
  * @prop {string} name - Describes your add-on and will appear in subscribers' invoices.
  * @prop {string} object - Object type
+ * @prop {number} usagePercentage - The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.
+ * @prop {string} usageType - Type of usage, returns usage type if `add_on_type` is `usage`.
  */
 class AddOnMini extends Resource {
   static getSchema () {
     return {
       accountingCode: String,
+      addOnType: String,
       code: String,
       externalSku: String,
       id: String,
       itemId: String,
+      measuredUnitId: String,
       name: String,
-      object: String
+      object: String,
+      usagePercentage: Number,
+      usageType: String
     }
   }
 }

lib/recurly/resources/MeasuredUnit.js

@@ -0,0 +1,41 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * MeasuredUnit
+ * @typedef {Object} MeasuredUnit
+ * @prop {Date} createdAt - Created at
+ * @prop {Date} deletedAt - Deleted at
+ * @prop {string} description - Optional internal description.
+ * @prop {string} displayName - Display name for the measured unit. Can only contain spaces, underscores and must be alphanumeric.
+ * @prop {string} id - Item ID
+ * @prop {string} name - Unique internal name of the measured unit on your site.
+ * @prop {string} object - Object type
+ * @prop {string} state - The current state of the measured unit.
+ * @prop {Date} updatedAt - Last updated at
+ */
+class MeasuredUnit extends Resource {
+  static getSchema () {
+    return {
+      createdAt: Date,
+      deletedAt: Date,
+      description: String,
+      displayName: String,
+      id: String,
+      name: String,
+      object: String,
+      state: String,
+      updatedAt: Date
+    }
+  }
+}
+
+module.exports = MeasuredUnit

lib/recurly/resources/SubscriptionAddOn.js

@@ -22,9 +22,10 @@ const Resource = require('../Resource')
  * @prop {string} revenueScheduleType - Revenue schedule type
  * @prop {string} subscriptionId - Subscription ID
  * @prop {string} tierType - The type of tiering used by the Add-on.
- * @prop {Array.<SubscriptionAddOnTier>} tiers - Empty unless `tier_type` is `tiered`, `volume`, or `stairstep`.
+ * @prop {Array.<SubscriptionAddOnTier>} tiers - If tiers are provided in the request, all existing tiers on the Subscription Add-on will be removed and replaced by the tiers in the request.
  * @prop {number} unitAmount - This is priced in the subscription's currency.
  * @prop {Date} updatedAt - Updated at
+ * @prop {number} usagePercentage - The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.
  */
 class SubscriptionAddOn extends Resource {
   static getSchema () {
@@ -41,7 +42,8 @@ class SubscriptionAddOn extends Resource {
       tierType: String,
       tiers: ['SubscriptionAddOnTier'],
       unitAmount: Number,
-      updatedAt: Date
+      updatedAt: Date,
+      usagePercentage: Number
     }
   }
 }

lib/recurly/resources/SubscriptionChange.js

@@ -18,6 +18,7 @@ const Resource = require('../Resource')
  * @prop {Date} createdAt - Created at
  * @prop {Date} deletedAt - Deleted at
  * @prop {string} id - The ID of the Subscription Change.
+ * @prop {InvoiceCollection} invoiceCollection - Invoice Collection
  * @prop {string} object - Object type
  * @prop {PlanMini} plan - Just the important parts.
  * @prop {number} quantity - Subscription quantity
@@ -37,6 +38,7 @@ class SubscriptionChange extends Resource {
       createdAt: Date,
       deletedAt: Date,
       id: String,
+      invoiceCollection: 'InvoiceCollection',
       object: String,
       plan: 'PlanMini',
       quantity: Number,

lib/recurly/resources/SubscriptionChangePreview.js

@@ -18,7 +18,7 @@ const Resource = require('../Resource')
  * @prop {Date} createdAt - Created at
  * @prop {Date} deletedAt - Deleted at
  * @prop {string} id - The ID of the Subscription Change.
- * @prop {InvoiceCollection} invoiceCollection - Invoice collection
+ * @prop {InvoiceCollection} invoiceCollection - Invoice Collection
  * @prop {string} object - Object type
  * @prop {PlanMini} plan - Just the important parts.
  * @prop {number} quantity - Subscription quantity

lib/recurly/resources/Usage.js

@@ -0,0 +1,49 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * Usage
+ * @typedef {Object} Usage
+ * @prop {number} amount - The amount of usage. Can be positive, negative, or 0. No decimals allowed, we will strip them. If the usage-based add-on is billed with a percentage, your usage will be a monetary amount you will want to format in cents. (e.g., $5.00 is "500").
+ * @prop {Date} billedAt - When the usage record was billed on an invoice.
+ * @prop {Date} createdAt - When the usage record was created in Recurly.
+ * @prop {string} id
+ * @prop {string} measuredUnitId - The ID of the measured unit associated with the add-on the usage record is for.
+ * @prop {string} merchantTag - Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.
+ * @prop {string} object - Object type
+ * @prop {Date} recordingTimestamp - When the usage was recorded in your system.
+ * @prop {string} tierType - The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based).
+ * @prop {Array.<SubscriptionAddOnTier>} tiers - The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = null
+ * @prop {Date} updatedAt - When the usage record was billed on an invoice.
+ * @prop {Date} usageTimestamp - When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.
+ * @prop {string} usageType - Type of usage, returns usage type if `add_on_type` is `usage`.
+ */
+class Usage extends Resource {
+  static getSchema () {
+    return {
+      amount: Number,
+      billedAt: Date,
+      createdAt: Date,
+      id: String,
+      measuredUnitId: String,
+      merchantTag: String,
+      object: String,
+      recordingTimestamp: Date,
+      tierType: String,
+      tiers: ['SubscriptionAddOnTier'],
+      updatedAt: Date,
+      usageTimestamp: Date,
+      usageType: String
+    }
+  }
+}
+
+module.exports = Usage

lib/recurly/resources/index.js

@@ -56,6 +56,7 @@ module.exports.UniqueCouponCode = require('./UniqueCouponCode')
 module.exports.CustomFieldDefinition = require('./CustomFieldDefinition')
 module.exports.Item = require('./Item')
 module.exports.Pricing = require('./Pricing')
+module.exports.MeasuredUnit = require('./MeasuredUnit')
 module.exports.BinaryFile = require('./BinaryFile')
 module.exports.Plan = require('./Plan')
 module.exports.PlanPricing = require('./PlanPricing')
@@ -66,3 +67,4 @@ module.exports.ItemMini = require('./ItemMini')
 module.exports.Tier = require('./Tier')
 module.exports.ShippingMethod = require('./ShippingMethod')
 module.exports.SubscriptionChangePreview = require('./SubscriptionChangePreview')
+module.exports.Usage = require('./Usage')