Ecommerce Store Credit

Follow

Store Credit is a feature within Agility Ecommerce that allows you to create credit which can be applied to the balance of an Order. This can only be used for online transactions for your ecommerce website.

Store credit can be used to cover partial or full Order amounts. In cases where the balance does not cover the entire Order amount, the customer will need to pay for the remainder using another valid payment provider (i.e. credit card).

Some common use cases for Store Credit include:

  1. You have a no-refund policy, however items can be returned in exchange for Store Credit which can be used for a future purchase on your website.

  2. You want to gift credit to a customer for a future purchase.

Sections:

Requirements

The following items are requirements in order to use Store Credit within your Ecommerce website:

  • You must have the Store Credit feature enabled - if you don't have this enabled, please contact your account manager or support@agilitycms.com

  • While you can create store credit directly in the Ecommerce Admin in Agility, you still need to have code in your website that allows users to either manually enter a code, or automatically apply an available store credit associated to that customer to an Order

Creating Store Credit Manually

  1. Go to Agility > Ecommerce > Store Credit and click New



    Fill out the following fields in the form:

    Name  = A friendly name representing this store credit (i.e. 'Credit for John Doe').

    Description = A description of why the store credit is being created.

    Code = This represents the number that is used for payment processing - similar to a credit card number.

    Balance = The remaining amount of credit.

    Amount = The initial credit to be applied.

    Allow Balance Owing = If set to True, this allows a customer to apply the store credit to an Order and checkout the Order even if the store credit does NOT cover the whole balance. 

    External ID = You may optionally set an External ID to a secure/unguessable string as another key to lookup and retrieve store credit.

    Active Date = The date this store credit will become active.

    Expiry Date = The date this store credit will expire and no longer be accepted as a valid form of payment.

    Disabled = If set to True, the store credit will not be accepted as a valid form of payment.

    Customer = If set, this store credit will be associated directly to this customer. If the customer is logged into the website, the store credit for that customer can be easily retrieved without requiring the customer to enter the store credit code for payment.

  2. After entering your fields, click Save to save the store credit.

Updating Store Credit Manually

  1. Go to Agility > Ecommerce > Store Credit and select an existing item from the list.

  2. You may update the NameDescriptionAmount*External IDActive DateExpiry DateDisabled, and Customer.

    *When updating the Amount field, you may only set this value to an amount that is higher than the current Balance.

  3. Click Save.

Creating Store Credit via Code

In many cases, it can be beneficial to automatically create Store Credit and assign it to a customer automatically based on your custom workflow.

An example of this could be to create store credit for a customer if they have requested a refund/return and a no-refund policy is in place.

You may only create store credit via code using the Ecommerce Service API (C#).

Example (C#):

var client = new Agility.Web.eCommerce.API.AgilityeCommerceService();
StoreCredit storeCredit = new StoreCredit()
{
    StoreCreditID = -1,
    ExternalID = externalID,
    ActiveDate = DateTime.Now,
    Disabled = false,
    CurrencyID = 1,
    Name = "Store Credit for John Doe,
    AmountMinorUnits = 10000, //$100.00
    CustomerID = customerID
};
client.CreateStoreCredit(storeCredit);

Paying with Store Credit

Creating and updating store credit is only half the battle. You still need to be able to actually 'pay' using store credit on your website. In this section, we'll walk through how you can create a payment provider for store credit, retrieve a customer's store credit, and use that to apply to an order.

Initialize Store Credit as a Payment Provider

In order to apply payments for orders using store credit, you must create a Payment Provider using Store Credit as the Type.

  1. Go to Agility > Ecommerce > Ecommerce Settings > Payment Providers

  2. Click New to create a new payment provider

  3. For the Name, enter 'Store Credit'

  4. For the Reference Name, enter 'store-credit'

  5. For Type, select 'Store Credit' from the dropdown

  6. Optionally, set a value for Description

  7. For Other Settings, enter the following JSON values, replacing "US" with your respective country code:

    { 
       "CountryCode": "US",
       "ProcessingCountryCode": "US",
       "QA": 
        {     
           "CountryCode": "US",
           "ProcessingCountryCode": "US"   
        }
    } 
  8. Click Save to save the payment provider

Retrieving a Logged-In Customer's Store Credit

At this time, there is no way to retrieve a customer's store credit code(s) using the JS API on the website. You must send the customer an email with the store credit code and must be manually inputted by the customer in order to be used.

An upcoming release will provide the a new method in the JS API to list store credit by the current logged-in customer, and allow the customer to select their store credit and not have to input the store credit code.

Applying Store Credit to an Order

You need to apply store credit to an order prior to calling the Checkout method. You need to do this regardless of whether the store credit will cover the whole order or only a partial amount. You can also apply multiple store credits to an order as needed.

Apply Store Credit API Request (js):

var data = {
    orderNumber: 'ABCD1234',
    paymentProviderReferenceName: 'store-credit',
    storeCreditCode: 1234567891012456
};
Agility.Ecommerce.API.Order.ApplyStoreCredit(data, function() {
    //success
},
function() {
    //error
},
function() {
   //always
});

Checking out an Order

After your store credit has been applied to an order. You need to calculate whether there is balance remaining on the order or not. This will influence the next step, in terms of whether you show a payment form or simply complete checkout. 

Calculating Remaining Balance of an Order

You can calculate if there is a remaining balance on an order by calling Order.Get and inspecting the array of store credits that have been applied.

Order.Get JS API Response (JSON):

 
{
  "IsError": false,
  "ErrorMessage": null,
  "ResponseData": {
    "OrderItems": [
      {
        "AltPrices": [
          {
            "VariantMeasureID": 5899,
            "Key": "gate",
            "PriceMinorUnits": 37000
          }
        ],
        "RestockingFeeMinorUnits": 0,
        "RestockingFeePercentValue": 0,
        "UsePercentValue": false,
        "OrderItemShipmentID": 0,
        "OrderItemID": 17765,
        "OrderID": 7505,
        "OrderLogID": 0,
        "ProductID": 0,
        "TicketID": 11354,
        "Sku": "T6060",
        "ProductDescription": "Disney Base Tickets | 4 Day Base Ticket | Adult | $15 Version",
        "PriceOverrideMinorUnits": 1500,
        "Quantity": 2,
        "QuantityRefundable": 0,
        "IsRefund": false,
        "ProductPriceMinorUnits": 34000,
        "ItemTotalMinorUnits": 3000,
        "PromoValueMinorUnits": 0,
        "VariantOfProductID": 0,
        "VariantOfTicketID": 11266,
        "RequiresManualFulfillment": true,
        "RequiresOrderItemValidation": true,
        "IsSingle": false,
        "Measure": "Adult",
        "ProductVariantMeasureID": 0,
        "ProductVariantMeasureUnitTitle": null,
        "ProductVariantTitle": null,
        "TicketVariantMeasureID": 5899,
        "TicketVariantMeasureUnitTitle": "Ticket",
        "TicketVariantTitle": null,
        "OrderItemStatusID": null,
        "ExternalID": null,
        "AdditionalJSON": null,
        "CreatedDate": "2018-09-28T16:12:40.553",
        "ModifiedDate": "2018-09-28T16:12:40.553",
        "Deleted": false
      }
    ],
    "PromotionIDs": [],
    "Promotions": [],
    "StoreCredits": [
      {
        "Logs": null,
        "BalanceMinorUnits": 14688733,
        "StoreCreditID": 2,
        "Name": "Tunc's Store Credit",
        "Description": "Testing store credit",
        "AmountMinorUnits": 0,
        "Code": "******5744",
        "Token": "0f46a41c0c0300fbac9b253f5af8edb80223955cac464a67bc58eabef8c038d1",
        "CustomerID": null,
        "CurrencyID": null,
        "ExternalID": null,
        "Disabled": false,
        "ActiveDate": "0001-01-01T00:00:00",
        "ExpiryDate": "2018-10-12T00:00:00",
        "AllowBalanceOwing": false,
        "CreatedDate": "0001-01-01T00:00:00",
        "ModifiedDate": "0001-01-01T00:00:00",
        "Deleted": false
      },
      {
        "Logs": null,
        "BalanceMinorUnits": 159000,
        "StoreCreditID": 5,
        "Name": "Tunc Store Credit 2",
        "Description": "Example storecredit",
        "AmountMinorUnits": 0,
        "Code": "******9390",
        "Token": "8379aef1c21caa67b54b665be267e860319d2826e9fb315f4057790a9a2faa52",
        "CustomerID": null,
        "CurrencyID": null,
        "ExternalID": null,
        "Disabled": false,
        "ActiveDate": "0001-01-01T00:00:00",
        "ExpiryDate": null,
        "AllowBalanceOwing": false,
        "CreatedDate": "0001-01-01T00:00:00",
        "ModifiedDate": "0001-01-01T00:00:00",
        "Deleted": false
      }
    ],
    "OrderID": 7505,
    "OrderNumber": "0D138546",
    "CustomerID": 5202,
    "ShippingAddressID": null,
    "BillingAddressID": null,
    "OrderStatusID": 0,
    "CurrencyID": 1,
    "SubscriptionID": 0,
    "SubscriptionNumber": null,
    "Currency": null,
    "Referrer": "https://visitorlandodevcopy.azurewebsites.net",
    "IPAddress": "72.142.98.138",
    "TotalAmountRefundedMinorUnits": 0,
    "ShippingCostMinorUnits": 2495,
    "ShippingDescription": null,
    "ShippedDate": null,
    "ShippingEstimatedArrivalDate": null,
    "TaxAmountMinorUnits": 0,
    "TaxDescription": null,
    "TrackingNumber": null,
    "TrackingURL": null,
    "Notes": "Arrival Date: Friday, September 28, 2018\nDeparture Date: Saturday, September 29, 2018",
    "AdditionalJSON": "{\"TravelDates\":{\"Arrival\":\"2018-09-28T04:00:00.000Z\",\"Departure\":\"2018-09-29T04:00:00.000Z\"},\"WebSource\":\"localhost\",\"Shipping\":{\"ShippingOption\":{\"Title\":\"FedEx International (Canada Only)()\",\"FixedCostMinorUnits\":2495,\"SalesForceReferenceID\":\"123\",\"ServiceLevelIdentifier\":\"INTERNATIONAL_ECONOMY\",\"ContentID\":3425}}}",
    "QAMode": true,
    "SubmittedDate": null,
    "ProcessedDate": null,
    "CompletedDate": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "TerminalOrder": null,
    "TotalValueMinorUnits": 5495,
    "TotalPromotionalValueMinorUnits": 0,
    "SubTotalValueMinorUnits": 3000,
    "QuantityRefundable": 0,
    "TotalAmountPaidMinorUnits": 0,
    "TotalAmountPreauthorizedMinorUnits": 0,
    "Shipments": [],
    "Returns": [],
    "CreatedDate": "2018-09-28T16:12:39.367",
    "ModifiedDate": "2018-09-28T16:29:34.717",
    "Deleted": false
  },
  "Token": null,
  "AdditionalValues": {},
  "IsManagementException": false,
  "StackTrace": null
}

In the above case, the combined BalanceMinorUnits of both applied store credit cards is greater than the order TotalValueMinorUnits (5495/$54.95) plus applicable taxes. In a more likely scenario, your website would have logic that prevents the user from adding more than one store credit if the the order balance can already be covered with one store credit.

Completing an Order Paid with Store Credit Only

Assuming you have enough balance with store credit to cover the whole order, the next step is to complete the order.

Checkout API Request (js):

Agility.Ecommerce.API.Order.Checkout(
{
    orderNumber: '0D138546',
    paymentProviderReferenceName: 'N\A', //no additional payment providers used, set to n/a
    paymentTypeHash: 'N\A', //no additional payment providers used, set to n/a
    currencyID: 1,
    taxAmountMinorUnits: 300,
    taxDescription: "",
    shippingAmountMinorUnits: 2495,
    shippingDescription: 'FedEx International (Canada Only)',
    billingAddressJson: '{"AddressID":8073,"CustomerID":null,"Title":"Tunc Ekiz","Line1":"123 Fake Street","Line2":null,"City":"Toronto","Province":"ON","PostalCode":"M1M 1M1","Country":"CA","Latitude":null,"Longitude":null,"IsBillingAddress":false,"IsShippingAddress":false}',
    shippingAddressJson: '{"AddressID":8073,"CustomerID":null,"Title":"Tunc Ekiz","Line1":"123 Fake Street","Line2":null,"City":"Toronto","Province":"ON","PostalCode":"M1M 1M1","Country":"CA","Latitude":null,"Longitude":null,"IsBillingAddress":false,"IsShippingAddress":false}',
    useStoreCredits: true //must be set to TRUE to utilize applied store credits
},
function (order) {
    //success
},
function (err) {
    //error
},
function () {
    //always
});

Combining Store Credit and another Payment Provider

In cases where the applied store credit does not have enough balance to complete an order, you must pay for the remainder using another payment provider. Typically this would be a credit card using one of the available payment provider integrations: StripeMonerisPayPal, or Exact.

Checkout API Request (js):

Agility.Ecommerce.API.Order.Checkout(
{
    orderNumber: '0D138546',
    paymentProviderReferenceName: 'Stripe-USD', //set your payment provider reference name
    paymentTypeHash: 'tok_1DFSimLjwcuEFMMJEh7zFLrq', //set your token that represents the credit card
    currencyID: 1,
    taxAmountMinorUnits: 300,
    taxDescription: "",
    shippingAmountMinorUnits: 2495,
    shippingDescription: 'FedEx International (Canada Only)',
    billingAddressJson: '{"AddressID":8073,"CustomerID":null,"Title":"Tunc Ekiz","Line1":"123 Fake Street","Line2":null,"City":"Toronto","Province":"ON","PostalCode":"M1M 1M1","Country":"CA","Latitude":null,"Longitude":null,"IsBillingAddress":false,"IsShippingAddress":false}',
    shippingAddressJson: '{"AddressID":8073,"CustomerID":null,"Title":"Tunc Ekiz","Line1":"123 Fake Street","Line2":null,"City":"Toronto","Province":"ON","PostalCode":"M1M 1M1","Country":"CA","Latitude":null,"Longitude":null,"IsBillingAddress":false,"IsShippingAddress":false}',
    useStoreCredits: true //must be set to TRUE to utilize applied store credits
},
function (order) {
    //success
},
function (err) {
    //error
},
function () {
    //always
});

 

 

 

 

 

 

 

 

 

 

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.