examples.md

#Documentation

NOTE: Requests that result in a 404 from the Recurly API will raise a NotFoundException.

• Accounts
• Adjustments
• BillingInfo
• Coupons
• Coupon Redemptions
• Invoices
• Plans
• Plan Addons
• Subscriptions
• Subscription Addons
• Manual Invoicing Subscriptions
• Transactions

#Accounts

• List
• Get
• Create
• Close
• Reopen
• List Account Notes

###List Accounts

using System.Linq;

var accounts = Accounts.List();
while (accounts.Any())
{
	foreach (var account in accounts)
		Console.WriteLine(account);
	accounts = accounts.Next;
}

###Get Account

try
{
	var account = Accounts.Get("1");
	Console.WriteLine("Account " + account);
}
catch (NotFoundException e)
{
	Console.WriteLine("Account not found.");
}

Please note: the client library will raise an exception if the account is not found.

###Create Account

var account = new Account("1")
{
	Email = "verena@example.com",
	FirstName = "Verena",
	LastName = "Example"
};
account.Create();

###Close Account

var account = Accounts.Get("1");
account.Close();

// or to avoid an API call
Accounts.Close("1");

###Reopen Account

var account = Accounts.Get("1");
account.Reopen();

// or to avoid an API call
Accounts.Reopen("1");

###List Account Notes

using System.Linq;

var account = Accounts.Get("1");
var notes = account.GetNotes();
while (notes.Any())
{
	foreach (var note in notes)
		Console.WriteLine("Note: " + note.Message);
	notes = notes.Next;
}

back to top

#Account Adjustments

• List
• Get
• Create
• Delete

###List adjustments

using System.Linq;

var account = Accounts.Get("1");
var adjustments = account.GetAdjustments();
while (adjustments.Any())
{
	foreach (var adjustment in adjustments)
		Console.WriteLine("Adjustment: " + adjustment);
	adjustments = adjustments.Next;
}

###Get adjustment

var adjustment = Adjustments.Get("123456789");
Console.WriteLine("Adjustment: " + adjustment);

###Create adjustment

var account = Accounts.Get("1");
var adjustment = account.NewAdjustment(
	"USD",                        // currency
	5000,                         // unit_amount_in_cents
	"Charge for extra bandwidth", // description
	1,                            // quantity
	"bandwidth",                  // accounting_code
	false);                       // tax_exempt
adjustment.Create();

###Delete adjustment

var adjustment = Adjustments.Get("123456789");
adjustment.Delete()

back to top

#BillingInfo

• Get
• Update
• Delete

###Get Billing Info

var account = Accounts.Get("1");
var info = account.BillingInfo;

###Update billing info

var account = Accounts.Get("1");
var info = account.BillingInfo;
info.FirstName = "Verana";
info.LastName = "Example";
info.PhoneNumber = "111-111-1111";
info.VerificationValue = "123";
info.ExpirationMonth = 11;
info.ExpirationYear = 2015;
info.Update();

// or update using a TokenId
var account = Accounts.Get("1");
var info = account.BillingInfo;
info.TokenId = "some-token-id";
info.Update();

###Delete billing info

var account = Accounts.Get("1");
account.DeleteBillingInfo();

back to top

#Coupons

• List
• Get
• Create
• Deactivate

###List active coupons

using System.Linq;

var coupons = Coupons.List();
while (coupons.Any())
{
	foreach (var coupon in coupons)
		Console.WriteLine("Coupon: " + coupon);
	coupons = coupons.Next;
}

###Get coupon

var coupon = Coupons.Get("special");

###Create coupon

// $2 off...
var coupon = new Coupon("special", "Special $2 off coupon", new Dictionary<string, int> {{"USD", 200}});

// ...or 10% off
var coupon = new Coupon("special", "Special 10% off coupon", 10);

// Other properties
coupon.RedeemByDate = new DateTime(2014, 1, 1);
coupon.SingleUse = true;

// Limit to gold and platinum plans only.
coupon.AppliesToAllPlans = false;
coupon.Plans.Add("gold");
coupon.Plans.Add("silver");

coupon.Create();

###Deactivate coupon

var coupon = Coupons.Get("special");
coupon.Deactivate();

back to top

#Coupon Redemptions

• Redeem coupon
• Lookup redemption
• Delete redemption
• Lookup an Invoice redemption

###Redeem a coupon

var account = Accounts.Get("1");
var redemption = account.Redeem("special", "USD");

###Lookup a redemption

var account = Accounts.Get("1");
var redemption = account.GetActiveRedemption();

###Delete redemption

var account = Accounts.Get("1");
var redemption = account.GetActiveRedemption();
redemption.Delete();

###Lookup a coupon redemption on an invoice

var invoice = Invoices.Get(1);
var redemption = invoice.GetRedemption();

back to top

#Invoices

• List
• List by Account
• Get
• Get Invoice PDF
• Create Invoice
• Mark paid
• Mark failed
• Line Item Refunds

###List Invoices

using System.Linq;

var invoices = Invoices.List();
while (invoices.Any())
{
	foreach (var invoice in invoices)
		Console.WriteLine("Invoice: " + invoice);
	invoices = invoices.Next;
}

###List an account's invoices

using System.Linq;

// Get the list of invoices through the Account
var account = Accounts.Get("1");
var invoices = account.GetInvoices();

// OR directly through Invoices
var invoices = Invoices.List("1"); // account code

while (invoices.Any())
{
	foreach (var invoice in invoices)
		Console.WriteLine("Invoice: " + invoice);
	invoices = invoices.Next;
}

###Get Invoice

var invoice = Invoices.Get(1005);

###Retrieve a PDF invoice

var invoice = Invoices.Get(1005);
byte[] pdf = invoice.GetPdf();

###Create an invoice: invoice pending charges on an account

var account = Accounts.Get("1");
var invoice = account.InvoicePendingCharges();

###Mark an invoice as paid successfully

var invoice = Invoices.Get(1005);
invoice.MarkSuccessful();

###Mark an invoice as failed collection

var invoice = Invoices.Get(1005);
invoice.MarkFailed();

###Line item refunds

var invoice = Invoices.Get(1005);

// refund a single adjustment
var adjustment = invoice.Adjustments.First(x => x.Uuid == "e1234245132465");
invoice = invoice.Refund(adjustment, false, 1); // adjustment, prorate, quantity

// refund with proration
var adjustment = invoice.Adjustments.First(x => x.Uuid == "e1234245132465");
invoice = invoice.Refund(adjustment, true); // adjustment, prorate

// refund multiple adjustments
invoice = invoice.Refund(invoice.Adjustments);

// with proration
invoice = invoice.Refund(invoice.Adjustments, true);

back to top

#Plans

• List
• Get
• Create
• Update
• Deactivate

###List plans

using System.Linq;

var plans = Plans.List();
while (plans.Any())
{
	foreach (var plan in plans)
		Console.WriteLine("Plan: " + plan);
	plans = plans.Next;
}

###Lookup plan details

var plan = Plans.Get("gold");

###Create plan

var plan = new Plan("gold", "Gold plan"); // plan code, name
plan.UnitAmountInCents.Add("USD", 1000);
plan.UnitAmountInCents.Add("EUR", 800);
plan.SetupFeeInCents.Add("USD", 6000);
plan.SetupFeeInCents.Add("EUR", 4500);
plan.PlanIntervalLength = 1;
plan.PlanIntervalUnit = Plan.IntervalUnit.Month;
plan.TaxExempt = false;
plan.Create();

###Update Plan

var plan = Plans.Get("gold");
plan.SetupFeeInCents["EUR"] = 5000;
plan.Update();

###Deactivate Plan

var plan = Plans.Get("gold");
plan.Deactivate();

back to top

#Plan Addons

• List
• Get
• Create
• Update
• Delete

###List plan add-ons

using System.Linq;

var plan = Plans.Get("gold");
var addons = plan.AddOns;
while (addons.Any())
{
	foreach (var addon in addons)
		Console.WriteLine("Addon: " + addon);
	addons = addons.Next;
}

###Lookup an add-on

var plan = Plans.Get("gold");
var addon = plan.GetAddOn("addOnCode");

###Create add-on

var plan = Plans.Get("gold");
var addon = plan.NewAddOn("ipaddresses", "Extra IP Addresses"); // add-on code, name
addon.UnitAmountInCents.Add("USD", 200);
addon.DefaultQuantity = 1;
addon.DisplayQuantityOnHostedPage = true;
addon.Create();

// accounting_code not yet supported.
// Please contact us if you need this.

###Update add-on

var plan = Plans.Get("gold");
var addon = plan.GetAddOn("ipaddresses");
addon.UnitAmountInCents["USD"] = 200;
addon.Update();

###Delete add-on

var plan = Plans.Get("gold");
var addon = plan.GetAddOn("ipaddresses");
addon.Delete();

back to top

#Subscriptions

• List
• Get
• Create
• Update
• Cancel
• Reactivate
• Terminate
• Postpone
• Preview

###List Subscriptions

using System.Linq;

var subscriptions = Subscriptions.List();
while (subscriptions.Any())
{
	foreach (var subscription in subscriptions)
		Console.WriteLine("Subscription: " + subscription);
	subscriptions = subscriptions.Next;
}

###List an account's subscriptions

using System.Linq;

var account = Accounts.Get("1");
var subscriptions = account.GetSubscriptions();
while (subscriptions.Any())
{
	foreach (var subscription in subscriptions)
		Console.WriteLine("Subscription: " + subscription);
	subscriptions = subscriptions.Next;
}

###Get subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");

###Create Subscription

var account = Accounts.Get("1"); // Account contains BillingInfo
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.Create();

###Update subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Plan = Plans.Get("silver");
subscription.Quantity = 2;

// perform the update operation now
subscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);

// ChangeTimeframe.Now is the default, so we can simply:
subscription.ChangeSubscription();

// You might also use `Subscription.ChangeTimeframe.Renewal`

###Cancel subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Cancel();

###Reactivating a canceled subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Reactivate();

###Terminate a subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Terminate(Subscription.RefundType.Full);
//subscription.Terminate(Subscription.RefundType.Partial);
//subscription.Terminate(Subscription.RefundType.None);

###Postpone a subscription

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Postpone(new DateTime(2012, 12, 31));

###Preview a subscription

var account = Accounts.Get("1");
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.Preview();

// preview subscription at renewal
subscription.Preview(Subscription.ChangeTimeframe.Renewal);
Debug.WriteLine(subscription.ExpiresAt);

back to top

#Subscription Add-ons

• Create with Addons
• Update with Addons

###Create a subscription with Add-Ons

var account = Accounts.Get("1");
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency

subscription.AddOns.Add("plan-addon-code"); // string (plan.AddOnCode)
subscription.AddOns.Add(plan.GetAddOn("another-addon-code")); // AddOn
subscription.AddOns.Add(new SubscriptionAddOn("extra_users", 1000, 2));
subscription.Create();

###Update subscription with add-ons

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");

// append a new add-on
var newAddOn = plan.GetAddOn("my-add-on");
subscription.AddOns.Add(newAddOn);

// change a quantity of an existing add-on
var existingAddOn = subscription.AddOns.AsQueryable().First(x => x.AddOnCode == "extra_ips");
existingAddOn.Quantity = 6;

// remove an add-on
subscription.AddOns.RemoveAt(0);

// remove all add-ons
subscription.AddOns.Clear();

// call for an update
subscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);

back to top

#Subscriptions for Manual Invoicing

• Create manual invoicing subscription
• Update manual invoicing subscription

###Create subscription (Manual Invoice)

var account = Accounts.Get("1");
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.CollectionMethod = "manual";
subscription.NetTerms = 10;
subscription.PoNumber = "PO1234";
subscription.Create();

###Update subscription (Manual Invoice)

var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.CollectionMethod = "manual";
subscription.NetTerms = 10;
subscription.PoNumber = "PO1234";
subscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);

back to top

#Transactions

• List
• List Account Transactions
• Get
• Create
  • with stored billing info
  • with new billing info
• Refund
  • Partial
  • Full

###List transactions

using System.Linq;

var transactions = Transactions.List();
while (transactions.Any())
{
	foreach (var transaction in transactions)
		Console.WriteLine("Transaction: " + transaction);
	transactions = transactions.Next;
}

// Filter successful Transactions
var transactions = Transactions.List(TransactionList.TransactionState.Success);

// Filter failed purchases
var transactions = Transactions.List(TransactionList.TransactionState.Success, TransactionList.TransactionType.Failed);

###List an account's transactions

using System.Linq;

var account = Accounts.Get("1");
var transactions = account.GetTransactions();
while (transactions.Any())
{
	foreach (var transaction in transactions)
		Console.WriteLine("Transaction: " + transaction);
	transactions = transactions.Next;
}

###Get transaction

var transaction = Transactions.Get("a13acd8fe4294916b79aec87b7ea441f");

###Create Transaction

####Example with stored billing info

var transaction = new Transaction("1", 100, "USD"); // account code, unit amount in cents, currency
transaction.Create();

####Example with new billing info

var account = Accounts.Get("1");
account.BillingInfo = new BillingInfo(account.AccountCode)
{
	FirstName = "Verana",
	LastName = "Example",
	CreditCardNumber = "4111-1111-1111-1111",
	VerificationValue = "123",
	ExpirationYear = 2015,
	ExpirationMonth = 11
};
var transaction = new Transaction(account, 100, "USD");
transaction.Create();

###Refund transaction

####Partial Refund

var transaction = Transactions.Get("a13acd8fe4294916b79aec87b7ea441f");
transaction.Refund(1000); // (in cents) Refund $10

####Full Refund

var transaction = Transactions.Get("a13acd8fe4294916b79aec87b7ea441f");
transaction.Refund();