API v2 .NET Client Upgrade Guide

This page is provided as an upgrade guide to all users of the official .NET client.

Two aspects of the upgrade process are covered:

• Given that version designations for client libraries do not support the same versioning system as the v2 API, we have provided a version mapping table directly below. You can use this table in order to determine which version of the v2 API that a specific client library version is utilizing.
• Breaking changes to client libraries are normally applied with a bump in the minor version. As an example, suppose you wish to upgrade from 1.6.3 to 1.15.4 while preserving current functionality: apply all changes listed in (1.7.0, 1.8.0, ..., 1.14.0). A guide to breaking changes between all versions of the client library can be found below.

Version Mapping Table

Guide to Breaking Changes

1.17.0

Adjustment#TaxExempt has been converted to nullable.

1.16.0

When updating an Invoice, the embedded Address object is only sent to the API if explicitly set on the object, and the following fields require an empty string to clear values:

• CustomerNotes
• TermsAndConditions
• VatReverseChargeNotes
• GatewayCode
• PoNumber

In the past, if you were to leave a value such as CustomerNotes null, it would nullify it via the API. Now, you must explicitly nullify it by setting it to empty string "". See this conversation for an example.

1.15.0

Note: this release contains a bug in SubscriptionAddoOn. Please use version 1.15.1 or higher instead.

This release contains two breaking changes:

1. Subscription Change Objects To update a subscription, a SubscriptionChange object must be passed into the ChangeSubscription() method. See the C# example for this endpoint.
2. Address class and Purchase po_number requires empty string to clear values In the past, if you were to leave a value such as FirstName null, it would nullify it via the API. Now, you must explicitly nullify it by setting it to empty string "". See this conversation for an example.

1.14.0

GiftCard#RedeemedAt and GiftCard#DeliveredAt are now nullable fields and now must be unwrapped. If you do not read these values, no change is needed.

1.13.0

The build now targets .NET v4.7. Please make sure that you update your application appropriately.

1.12.0

SubscriptionAddOn#UnitAmountInCents was changed to nullable type. If you do not read this value, no change is needed.

1.11.0

1. InvoiceCollection

   When creating or failing invoices, we now return an InvoiceCollection object rather than an Invoice. If you wish to upgrade your application without changing functionality, we recommend that you use the ChargeInvoice property on the InvoiceCollection to get the charge Invoice. Example:

    // Change this:
    var invoice = account.InvoicePendingCharges();
   
    // To this
    var invoiceCollection = account.InvoicePendingCharges();
    var invoice = invoiceCollection.ChargeInvoice;
   
    // Invoice.MarkFailed now returns a new collection
    // Change this
    invoice.MarkFailed();
   
    // To this
    var invoiceCollection = invoice.MarkFailed();
    var failedInvoice = invoiceCollection.ChargeInvoice;
   

2. Invoice Subtotal* changes

   If you want to preserve functionality, change any use of Invoice#SubtotalAfterDiscountInCents to Invoice#SubtotalInCents. If you were previously using Invoice#SubtotalInCents, this has been changed to Invoice#SubtotalBeforeDiscountInCents.

3. Invoice Refund – refund_apply_order changed to refund_method

   The RefundOrderPriority enum was changed to RefundMethod. Change use of RefundOrderPriority.Credit to RefundMethod.CreditFirst and RefundOrderPriority.Transaction to RefundMethod.TransactionFirst.

4. Invoice States

   If you are checking Invoice#State anywhere, you will want to check that you have the new correct values. collected has changed to paid and open has changed to pending. Example:

    // Change this
    if (invoice.State == Invoice.InvoiceState.Collected) {
    // To this
    if (invoice.State == Invoice.InvoiceState.Paid) {
   
    // Change this
    if (invoice.State == Invoice.InvoiceState.Open) {
    // To this
    if (invoice.State == Invoice.InvoiceState.Pending) {
   

5. Invoices on Subscription Previews

   If you are using Subscription#Invoice on subscription previews, you will need to change this to use Subscription#InvoiceCollection. To keep functionality the same:

    // Change this
    subscription.Preview();
    var invoice = subscription.Invoice;
   
    // To this
    subscription.Preview();
    var invoice = subscription.InvoiceCollection.ChargeInvoice;
   

1.10.0

Coupon#Id changed from an int to a long. Your code will require a change if you explicitly reference it as an int.

1.9.0

There is a small set of breaking changes coming from PR #263. These properties have been converted to nullable so you may have to unwrap them to use them. If you do not read these values anywhere, no changes will be needed.

• AddOn#DefaultQuantity
• Plan#PlanIntervalLength
• Plan#TrialIntervalLength
• GiftCard#BalanceInCents

1.8.0

Plan#TrialRequiresBillingInfo is now an nullable so you will have to unwrap it to use it. If you do not read this value anywhere, no change will be needed.

1.7.0

Country Codes

All Country fields must now contain valid 2 letter ISO 3166 country codes. If your country code fails validation, you will receive a validation error. This affects any endpoint where an address is collected.

Purchase Currency

The purchases endpoint can create and invoice multiple adjustments at once but our invoices can only contain items in one currency. To make this explicit the currency can no longer be provided on an adjustment, it must be set once for the entire purchase:

// You must set the currency here
var purchase = new Purchase(accountCode, currency);

var adj = new Adjustment(4000, "HD Camera", 5);
// You can no longer set the currency on the adjustment level
adj.Currency = currency;
purchase.Adjustments.Add(adj);

1.6.0

Invoice will now use an enum for the CollectionMethod property instead of a string. The enum has 2 values (Automatic and Manual). Example:

// Setting
invoice.CollectionMethod = Invoice.Collection.Manual;

// Getting
if (invoice.CollectionMethod == Invoice.Collection.Automatic)
{
  // do something
}

1.5.0

1. To speed up your listing requests we’re no longer automatically computing the record counts for each requests. For our larger sites this could halve the response time. So in this release, we are removing the RecurlyList#Capacity method. For more info see PR #324.
2. For POST /v2/subscriptions Sending null for total_billing_cycles attribute will now override plan total_billing_cycles setting and will make subscription renew forever. Omitting the attribute will cause the setting to default to the value of plan total_billing_cycles.

1.4.0

No breaking changes to address.

1.3.0

Retargeted to .NET v4.5 and explicitly constrained TLS versions: https://github.com/recurly/recurly-client-dotnet/pull/129 This may or may not be a breaking change depending on your targeted environment.

1.2.0

No breaking changes to address.