Class GiftCardService

Namespace

Dynamicweb.Ecommerce.GiftCards

Assembly

Dynamicweb.Ecommerce.dll

Manages the whole life cycle of gift cards: issuing them when an order containing gift card lines is completed, applying and redeeming them against later orders, and reading their remaining balance.

public class GiftCardService

Inheritance

object

GiftCardService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A gift card's balance is not stored on the card. It is derived from the GiftCardTransaction records written against it - one crediting the card when it is issued, and one debiting it for each redemption - so GetGiftCardBalance(GiftCard) is always computed rather than read.

Redemption codes are held encrypted, both on the gift card and on the discount order line that carries a card, which is why lookups by code take a flag saying whether the caller already has the encrypted form.

Redemption is serialized across callers, so two concurrent checkouts cannot both spend the last of the same card.

Methods

CreateGiftCards(Order)

Issues one gift card per purchased gift card on the order.

public virtual void CreateGiftCards(Order order)

Parameters

order Order

The order whose gift card lines should be issued.

Remarks

Gift card order lines with a quantity above one are first split into separate lines of quantity one, so that each purchased gift card gets its own card and code. Failures for an individual card are logged and recorded against the order rather than aborting the remaining cards.

Exceptions

ArgumentNullException

Thrown when order is null.

DecryptCode(string)

Decrypts a gift card code back to the value a customer would recognise.

public virtual string DecryptCode(string input)

Parameters

input string

The encrypted code.

Returns

string

The plain code.

Exceptions

ArgumentException

Thrown when input is null or empty.

DeleteGiftCard(GiftCard)

Deletes a gift card.

public virtual void DeleteGiftCard(GiftCard giftCard)

Parameters

giftCard GiftCard

The gift card to delete.

Exceptions

ArgumentNullException

Thrown when giftCard is null.

DeleteGiftCardTransaction(GiftCardTransaction)

Deletes a gift card transaction, returning the amount it held to the gift card's balance.

public virtual void DeleteGiftCardTransaction(GiftCardTransaction transaction)

Parameters

transaction GiftCardTransaction

The transaction to delete.

Exceptions

ArgumentNullException

Thrown when transaction is null.

EncryptCode(string)

Encrypts a gift card code, as stored on the gift card and on discount order lines.

public virtual string EncryptCode(string input)

Parameters

input string

The plain code.

Returns

string

The encrypted code.

Exceptions

ArgumentException

Thrown when input is null or empty.

GetAllGiftCards()

Gets every gift card in the solution.

public virtual IEnumerable<GiftCard> GetAllGiftCards()

Returns

IEnumerable<GiftCard>

All gift cards.

GetGiftCardBalance(GiftCard)

Gets the amount still available on a gift card, after every transaction recorded against it.

public virtual double GetGiftCardBalance(GiftCard giftCard)

Parameters

giftCard GiftCard

The gift card.

Returns

double

The remaining balance, or 0 when giftCard is null.

GetGiftCardByCode(string, bool)

Gets a gift card by its redemption code.

public virtual GiftCard? GetGiftCardByCode(string giftCardCode, bool encoded)

Parameters

giftCardCode string

The gift card code.

encoded bool

true when giftCardCode is already encrypted, as it is when read back off an order line; false when it is the plain code a customer entered.

Returns

GiftCard

The matching gift card, or null when none exists or giftCardCode is null or empty.

GetGiftCardById(string)

Gets a gift card by its identifier.

public virtual GiftCard? GetGiftCardById(string giftCardId)

Parameters

giftCardId string

The gift card identifier.

Returns

GiftCard

The matching gift card, or null when none exists or giftCardId is null or empty.

GetGiftCardTransaction(int)

Gets a gift card transaction by its id.

public virtual GiftCardTransaction? GetGiftCardTransaction(int transactionId)

Parameters

transactionId int

The transaction id.

Returns

GiftCardTransaction

The matching transaction, or null when none exists or the id is not greater than zero.

GetGiftCardsForOrder(string)

Gets the gift cards issued by an order.

public virtual IEnumerable<GiftCard> GetGiftCardsForOrder(string orderId)

Parameters

orderId string

The order id.

Returns

IEnumerable<GiftCard>

The gift cards issued by the order, or an empty sequence when orderId is null or empty.

GetGiftCardsForOrderLine(string)

Gets the gift card issued by a single order line.

public virtual GiftCard? GetGiftCardsForOrderLine(string orderLineId)

Parameters

orderLineId string

The order line id.

Returns

GiftCard

The matching gift card, or null when none exists or orderLineId is null or empty.

GetTransactionsForGiftCard(string)

Gets every transaction recorded against a gift card, which together determine its remaining balance.

public virtual IEnumerable<GiftCardTransaction> GetTransactionsForGiftCard(string giftCardId)

Parameters

giftCardId string

The gift card identifier.

Returns

IEnumerable<GiftCardTransaction>

The transactions, or an empty sequence when giftCardId is null or empty.

SaveGiftCard(GiftCard)

Creates or updates a gift card in the database.

public virtual void SaveGiftCard(GiftCard giftCard)

Parameters

giftCard GiftCard

The gift card to save.

Exceptions

ArgumentNullException

Thrown when giftCard is null.

SaveGiftCardTransaction(GiftCardTransaction)

Creates or updates a gift card transaction, the record that draws an amount down from a gift card.

public virtual void SaveGiftCardTransaction(GiftCardTransaction transaction)

Parameters

transaction GiftCardTransaction

The transaction to save.

Exceptions

ArgumentNullException

Thrown when transaction is null.

SetCardAsExpired(GiftCard)

Expires a gift card immediately by setting its expiry date to now, and saves it.

public virtual void SetCardAsExpired(GiftCard giftCard)

Parameters

giftCard GiftCard

The gift card to expire.

Exceptions

ArgumentNullException

Thrown when giftCard is null.

UseGiftCards(Order)

Redeems the gift cards applied to an order, writing one transaction per gift card discount line.

public virtual void UseGiftCards(Order order)

Parameters

order Order

The order to redeem the applied gift cards on.

Remarks

Each gift card is drawn down by at most the remaining order total, and a card is only charged when its balance covers the amount. If any card fails the order is flagged with GiftCardTransactionFailed; if a discount line had to be reduced the order is re-calculated. Redemption is serialized across callers.

Exceptions

ArgumentNullException

Thrown when order is null.