Copied to clipboard

Flag this post as spam?

This post will be reported to the moderators as potential spam to be looked at

  • Ismael 65 posts 337 karma points
    Jul 09, 2015 @ 03:48

    Alternate use for Merchello?


    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..)


  • Alex Lindgren 158 posts 355 karma points
    Jul 09, 2015 @ 14:27
    Alex Lindgren

    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.



  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jul 09, 2015 @ 16:41
    Rusty Swayne

    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)

             <type alias="Donation" descriptiveName="A donation" typeKey="676A3E0D-AC88-4D61-850A-403E8C359FDE" />

    Then create a class to build your invoice

      //// 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);
     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);
      // This will be added to the interface
      ((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);
     //// 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[] ("")); 
  • Ismael 65 posts 337 karma points
    Jul 09, 2015 @ 18:57

    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!


  • Biagio Paruolo 1494 posts 1635 karma points c-trib
    Jul 11, 2015 @ 19:28
    Biagio Paruolo

    How do typeFieldDefinitions ?

  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jul 13, 2015 @ 15:33
    Rusty Swayne

    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:

        <type alias="CcFee" descriptiveName="Fee applied to invoices for credit card charges" typeKey="676A3E0D-AC88-4D61-850A-403E8C359FDE" />

    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.


      LineItemType.CcFee  // will not exists.

    instead it will be

     LineItemType.Custom // along with every other custom line item type you define

    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.

  • Biagio Paruolo 1494 posts 1635 karma points c-trib
    Aug 13, 2015 @ 14:18
    Biagio Paruolo

    I need to understand better.

  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Aug 15, 2015 @ 16:37
    Rusty Swayne

    @Biagio - can you explain your use case so that I can understand what context you intend on using custom line items types.

  • Biagio Paruolo 1494 posts 1635 karma points c-trib
    Aug 20, 2015 @ 11:06
    Biagio Paruolo

    So, lineItem are a particular type of basket item or InvoiceLindeItem.


    • lineItem Donation: Is't visible to the customer? Is't visible into backoffice?
    • typeKey: Is't unique?
    • lineitem: Could store text, image, and so?
    • Is't the same if I create a "Donation" product into backoffice and not lineItem?
  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Aug 20, 2015 @ 14:50
    Rusty Swayne

    @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.


    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)

Please Sign in or register to post replies

Write your reply to: