A client would like to add a "donation" option to their site, long term will also want an actual shop solution. The client also wants the ability to alter the donation options.
Could I use Merchello to handle a donation type workflow? for example, A user clicks a Donate now button, is presented with a single page that has maybe a list of options (ie $10, $20 etc, maybe there can be products?) maybe also some custom fields, then clicks a Submit button - Merchello handles it by passing it off to the payment provider, then records the transactions etc.. So, kinda like a shop, but just doesn't look like shop (ie no cart etc..)
We used Merchello for donations for a project last year. I created a Web API controller that processed the donation form via AJAX. My code is kind of messy and we were working with an earlier version of Merchello (1.4), so I'm not sure it is worth sharing. Here's an overview of what I did:
Use the InvoiceService to create a new invoice.
Add the donation as a new InvoiceLineItem (I created a custom lineItem type for donation in merchello.config)
Save the invoice with the InvoiceService
invoice.PrepareOrder()
get payment gateway method and call AuthorizeCapturePayment
We ended up creating our own email notification method. Also, I ended up storing some info about the donation in a custom table. I had to hack (fork) Merchello backend to display my custom lineitemtype and the custom data in with the order. Rusty has reworked the backoffice quite a bit since then, so it might be more extensible.
If you don't plan on selling products, I would ask yourself if you really need Merchello. I just did a donation form for another site where I ended up just calling the payment processor directly. I think Merchello is great and has a lot of promise but sometimes its good to keep it simple.
Merchello has been used to take donations several times that I know of and is a good fit if you want to have an accounting of the donations in the back office and/or you would like to be able to do things like show the customer a list of donations they have made, give them some sort of perk or need to do something in the site as a result of their donation (karma, change a membership group, add a free product based on amount, etc).
Things have come a long way from version 1.4 and customer line item types are supported in the back office.
Alex's methodology looks good except I don't think you will need the invoice.PrepareOrder() .... that is usually handled internally and gets things setup for some something to be shipped.
Here is a quick snippet to get you going (I'm just writing free form so it may need some tweaks)
In /App_Plugins/Merchello/Config/merchello.config
Define a line item type outside of Merchello (or you could use a product)
//// Customer
// If you want to use a Merchello Customer (for billing history), you would need to have the member sign in with a MemberType set in the merchello.config file
var context = new CustomerContext(UmbracoContext.Current);
var customer = context.CurrentCustomer;
//// Billing address
var billingAddress = new Address()
{
Name = "Somewhere",
Address1 = "1234 Out There",
Locality = "Bellingham",
Region = "WA",
PostalCode = "98225",
CountryCode = "US"
};
// You can save addresses with the customer so they don't have to enter them again
// For this you would need to get a "Label" as well
var customerAddress = billingAddress.ToCustomerAddress(customer, "[SOME LABEL]", AddressType.Billing);
customer.SaveCustomerAddress(customerAddress)
var invoiceService = MerchelloContext.Current.Services.InvoiceService;
// Get an unpaid invoice status as we will apply a payment to it in a later step
var invoiceStatus = invoiceService.GetInvoiceStatusByKey(Merchello.Core.Constants.DefaultKeys.InvoiceStatus.Unpaid);
var invoice = invoiceService.CreateInvoice(Constants.DefaultKeys.InvoiceStatus.Unpaid);
invoice.SetBillingAddress(billingAddress);
// This will be added to the interface
// http://issues.merchello.com/youtrack/issue/M-434
((Invoice)invoice).CustomerKey = customer.Key;
// The version key is useful in some cases to invalidate shipping quotes or taxation calculations
invoice.VersionKey = Guid.NewGuid();
//// Get the custom lineitem type
var tf = EnumTypeFieldConverter.LineItemType.CustomTypeFields.FirstOrDefault(x => x.TypeKey == new Guid("676A3E0D-AC88-4D61-850A-403E8C359FDE"));
// you can store extra information in an extended data collection
var extendedData = new ExtendedDataCollection();
extendedData.SetValue(Constants.ExtendedDataKeys.CurrencyCode, "USD");
extendedData.SetValue("customerNote", "Happy to help");
var item = new InvoiceLineItem(tf.TypeKey, tf.Name, tf.Name, 1, 10M, extendedData);
invoice.Items.Add(item);
//// The authorize/capture the payment
var args = new ProcessorArgumentCollection();
// add whatever args are required by the provider (if any)
var result = invoice.AuthorizeCapturePayment([paymentMethodKey], args);
//// Send a notification
Notification.Trigger("OrderConfirmation", result, new[] ("[email protected]"));
@Biagio - all line items in Merchello implement an interface - ILineItem so that they can be easily converted from one to another.
Line items for a basket / wish list are ItemCacheLineItems. These get converted to InvoiceLineItem(s) when an invoice is created and then some get converted into OrderLineItem(s) - generally any items that are shipping or need to be fulfilled.
Example:
Customer adds Product-1 to a basket.
ItemCacheLineItem of LineItemType = Product is created.
Checkout Workflow ->
CurrentCustomer.Basket().SalePrepartion()
SalePreparation creates an entirely new ItemCache and duplicates the product line item.
Shipping quote is saved as a ItemCacheLineItem to SalePrep ItemCache.
SalePreparation.PrepareInvoice()
Creates an invoice and converts all line items to InvoiceLineItem(s) and adds
InvoiceLineItem of LineItemType = Taxation
and any
InvoiceLineItem of LineItemType = Discount
By default when the order is "approved" generally by having a payment captured
Invoice.PrepareOrder()
Filters "fulfillable" line items (generally products) and copies them to an order. In the above example, the tax line item and shipping line item would not exist in the order.
Any custom line item types created by defining them in the Merchello.config would appear as LineItemType.Custom in the back office but have unique LineItemTfKey values (GUIDs defined in the Merchello.config)
Alternate use for Merchello?
Hi,
A client would like to add a "donation" option to their site, long term will also want an actual shop solution. The client also wants the ability to alter the donation options.
Could I use Merchello to handle a donation type workflow? for example, A user clicks a Donate now button, is presented with a single page that has maybe a list of options (ie $10, $20 etc, maybe there can be products?) maybe also some custom fields, then clicks a Submit button - Merchello handles it by passing it off to the payment provider, then records the transactions etc.. So, kinda like a shop, but just doesn't look like shop (ie no cart etc..)
Cheers
We used Merchello for donations for a project last year. I created a Web API controller that processed the donation form via AJAX. My code is kind of messy and we were working with an earlier version of Merchello (1.4), so I'm not sure it is worth sharing. Here's an overview of what I did:
We ended up creating our own email notification method. Also, I ended up storing some info about the donation in a custom table. I had to hack (fork) Merchello backend to display my custom lineitemtype and the custom data in with the order. Rusty has reworked the backoffice quite a bit since then, so it might be more extensible.
If you don't plan on selling products, I would ask yourself if you really need Merchello. I just did a donation form for another site where I ended up just calling the payment processor directly. I think Merchello is great and has a lot of promise but sometimes its good to keep it simple.
Alex
Alex
Merchello has been used to take donations several times that I know of and is a good fit if you want to have an accounting of the donations in the back office and/or you would like to be able to do things like show the customer a list of donations they have made, give them some sort of perk or need to do something in the site as a result of their donation (karma, change a membership group, add a free product based on amount, etc).
Things have come a long way from version 1.4 and customer line item types are supported in the back office.
Alex's methodology looks good except I don't think you will need the invoice.PrepareOrder() .... that is usually handled internally and gets things setup for some something to be shipped.
Here is a quick snippet to get you going (I'm just writing free form so it may need some tweaks)
In /App_Plugins/Merchello/Config/merchello.config Define a line item type outside of Merchello (or you could use a product)
Then create a class to build your invoice
Thank Alex and Rusty,
The client does have plans to sell products and we were thinking of using Merchello for that - it's great that we can also use it for donations!
Cheers
How do typeFieldDefinitions ?
TypeFieldDefinitions are a construct in Merchello that allows us to use a standard "Enum" in C# for common types - like LineItemType
and still allow developers to use a line item for something different - like a Credit Card Fee or something.
You can add your own types in the Merchello.Config file:
The alias and typeKey need to be unique.
You will usually find classes that use them with a Constructor that takes an argument suffixed with TfKey - like lineItemTfKey.
Note: Every custom type field will be translated to "Custom" when looked at from the perspective of an enum.
Example:
instead it will be
If you use custom type fields, you can NOT instantiate a class with the LineItemType.Custom you MUST use the constructor with your custom key.
I need to understand better.
@Biagio - can you explain your use case so that I can understand what context you intend on using custom line items types.
So, lineItem are a particular type of basket item or InvoiceLindeItem.
Question:
@Biagio - all line items in Merchello implement an interface - ILineItem so that they can be easily converted from one to another.
Line items for a basket / wish list are ItemCacheLineItems. These get converted to InvoiceLineItem(s) when an invoice is created and then some get converted into OrderLineItem(s) - generally any items that are shipping or need to be fulfilled.
Example:
Customer adds Product-1 to a basket.
ItemCacheLineItem of LineItemType = Product is created.
Checkout Workflow ->
SalePreparation creates an entirely new ItemCache and duplicates the product line item.
Shipping quote is saved as a ItemCacheLineItem to SalePrep ItemCache.
Creates an invoice and converts all line items to InvoiceLineItem(s) and adds
InvoiceLineItem of LineItemType = Taxation
and any
InvoiceLineItem of LineItemType = Discount
By default when the order is "approved" generally by having a payment captured
Filters "fulfillable" line items (generally products) and copies them to an order. In the above example, the tax line item and shipping line item would not exist in the order.
Any custom line item types created by defining them in the Merchello.config would appear as LineItemType.Custom in the back office but have unique LineItemTfKey values (GUIDs defined in the Merchello.config)
is working on a reply...