Invoice Manager

Ecommerce Overview Roles People who can buy using an account - everyone with the account selected in their people record. People who can access account information and pay bills - the account contact and the account billing contact selected in the account Pay methods and Pay Options Pay Methods - a list of hardcoded choices that determine how to process a charge. Each account has one pay method set. The default is pay on demand. No Payment Necessary All orders will be automatically paid as $0 Pay on demand For online purchases, a credit card is required. For batch purchases, and on-demand option must be set in the account Bill and fulfill on payment Send a bill to the account. Fulfill (ship) the order when payment received Bill and fulfill immediately Send a bill but ship the order now PayOptions - used for the catalog system - a table of possible selections that an online user can choose when purchasing an order. Each PayOption includes a PayMethod to be used during the purchase. The online purchaser will only see the options that apply to them, based on their account settings. Pay Option set to No Payment - only available if account is set to no payment. Pay Option set to Pay on demand - available to everyone Pay Option set to Bill and fulfull on payment - everyone Pay Option set to Bill and fulfull immediately - required account set to bill and fulfull immediately. For an order to be no-payment, the account must be set to no-payment Pay method, and the site must include a pay option set to no-payment. Orders are can be created anonymously (without a userid or accountid), but to purchase an order must include a userId and accountid. Setting the userId will use the accountid in the user’s record. Setting the accountID will use the user in the account contact or billing contact. Any memberships can only go to this userId. Purchases through the site can be paid by an Account -- no longer by people record. Will consider cp.account.properties and methods to make this easy for custom forms Account Transactions are recorded for each charge and for each payment. Account Transactions is an asset account, so a change increases and is a Debit. A payment to Account Transactions decreases the balance and is a Credit. orders.readyToBatchComplete - default false. Set true when order is done if you want the system to automatically complete the order in the next batch. stages of an order Open - it can be modified readyForBatchComplete true - the system will complete and pay/bill it. Completed (dateCompleted set) - it has been ‘billed’ and can not be changed. This means it has been charged to the customers account and needs to be paid. Paid (payDate set) - it has been paid orders.paidByTransactionId - set when a payment is accepted. Later we can convert these into many-to-many rules so an order can be paid by 2+ transactions. ShoppingCart process All the same until they hit the buy-my button call processOrder addon with the orderId, act on it’s result Upgrading shoppingCart Orders in processBatch. if orders.ccNumber is not null, an order is considered paid. if an order is complete and it has no charge transactions, create charges create a payment and set payDate and .paidByTransactionId use the order completed date Background Process: ProcessBatchClass - runs periodically housekeeps recurring purchases and orders - check integrity creates orders out of recurring purchases, marks them readyToBatch bills all orders marked .readyToBatchProcess - billing means: clear readyToBatch checks order for valid conditions sets up charge transactions marks order complete sends invoices for appropriate paymethods iterates through completed orders without payment transaction and attempts payment. sends statements if account balance not zero “Process Order” addon process orders manually (readyToBatchProcess must be false) returns true or false on result argument “orderId” argument “RetryOnFail” if false and payment fails returns false (“0”) order is not completed no trans made if true and payment fails returns true (“1”) order completed charge trans made pay trans is not approved. orders.paidByTransactionId is 0. orders.payDate is null if return is 0 - there was a problem, the order record has the description if return true - the order processed. Completed is true and transactions are good moves order to completed orders and marks them complete. creates charge transactions for the order -- transactions point to order - When an order is completed, each order detail creates a separate transaction. Tax and shipping create their own transactions. pays orders -- attempts appropriate payment based on account payment transactions point to order (not to charge transactions) returns status message on fail For recurring purchases, Iterate through recurrings and create orders + order details + charge transactions for each order detail (and for tax and for shipping) Iterate through unpaid orders and pay them or bill them. When paying them, create Important invoice dates and periods Purchase Date - For credit card purchases, this is just the date of the purchase. For billing, this is the date that the purchase should take place. For instance, for a service, this is the date the service will start. For a membership, this is when the membership starts. For online purchases, this is the date of purchase. For recurring purchases with no pre-bill period this is the invoice date. Invoice Date - the date that the order is billed. Due Date - when payment is expected. Account Terms.Days to Pay (for billing accounts only) -- this is the number of days after the purchase date that the customer has to pay. Prebill Days (for recurring purchases and billing accounts only ) -- this is the number of days before the purchase date that the recurring purchase is to be invoiced. Example recurring annual membership, expires January 31. prebill set to 30 days days to pay set to 10 days Purchase Date = February 1 Invoice Date = January 2 (30 days before the purchase date) Date Due = February 11 (10 days after the Purchase Date) For online commerce, an order is created with order details -- when committed the online process calls Process orders and completes the order by either billing it (and possibly paying it also) Orders represent a single purchase that may include multiple An Order Detail is a line item of and describes one item purchase. An Invoice is the receipt (or bill) for a single Order Every people record has an account drop-down. This is the account they use to purchase. Default table prefix - “ab” Special Case for shopping cart upgrade - if orders.ccNumber is not null, the order will be considered paid. This is to prevent legacy orders that are marked complete from being paid again because they upgraded and orders.paidByTransactionid is null. (orders.orderComplete used to mean paid but now just means billed) Special case for adding and item to the cart -- if the item has a contentControlId that matches “membership types”, then the cart is cleared before when the item is added. Blocking duplicate purchases - When a membership/subscription is purchased, it creates a recurring purchase that automatically recharges the customer when the scubscription expires. To prevent the customer from purchasing the product again and creating two automatic charges, check the checkbox in the appropriate item Block Duplicate Recurring Purchases. limiting the quantitiy of an item for an order - use the Max Quantity per order field in the Puchase tab of the item to limit the number that can be purchased on one order. Ecommerce Cart If the user is not authenticated, the order belongs to the visit/visitor Once a user logs in, the order is populated with his userid and the visit/visitor no longer has access (logout and you lose it) A user can use the account selected in his user record to purchase. A user can edit the account if they are either the contact or billing contact for the account My Account Addon A public addon that lets account contacts pay invoices with a credit card they enter. Contensive Events Any addon can create an Addon Event record. These event records can be manually created or will be created automatically when the addon throws them.

It can then throw the event with a cp method, like cp.site.throwEvent( “My Event” )

Any addon can register for the event with a checkbox in in a tab of the Addon record. When an addon is registered, it is called by contensive when the calling addon calls cp.site.throwEvent.

Arguments should be passed with document properties.

Item Fulfill Event ecommerce.fulfillOrder

Called when an order is to be fulfilled.

Arguments: OrderId: The order that needs to be fulfullled

Fulfillment for an order would include things like adding people to groups they purchase or mailing an item out. When the Fulfillment event occurs depends on the Pay Method. On Demand: Fulfillment happen at the time of the purchase Bill: Fulfillment happends when the bill is paid Bill and Fulfill: fulfillment happens when the bill is sent. Calculate order details event ecommerce.calculateOrderDetails

Called after calculating the amounts for each order detail in an order, and before calculating the shipping, taxes and total. use this to calculate a custom amount for an item . Arguments: OrderId: The order that is being calulated Membership Management Overview (see Membership Spec for details) Contensive Support Overview The contensive support collection now includes the site support information which previously was in Account Billing. That is the only change. Shopping Cart Collection There will be no immediate changes to the shopping cart. After the Member Management and Account Management release, the shopping cart will be integrated into Account Management as follows: Completed Orders will create Transactions Account Management will handle all the reporting. Migration path for orders Must keep old orders from being paid again Legacy orders: orders.orderComplete - order is paid orders.ccNumber - only set when order is actually paid New orders: orders.orderComplete - order is billed orders.paidByTransactionId - order is paid if paidByTransactionId is null and ccNumber is not null, paidByTransactionId is set to -1 and payDate is set to dateCompleted Authoritative Sites during transition Shopping Cart - The authoritative site will be jay3-shopping. Member Management - The authoritative Site will be jay3-membersmart Account Management - Authoritative jay-membersmart Support - authoritative will be live support. membersmart.sitefpo.com - test site for all together Changes to existing addons Shopping Cart As few changes as possible. Items, Orders and Order Details will not change. A few fields will be added. When an order is completed, it will create a purchase transaction. If it paid as well, a charge transaction will also be made at the same time. Offline payments will create a purchase but no charge. Online payments will make no transactions unless they are complete items - get a new fields Include-In-Catalog, checkbox, default checked. Account Billing items replace products public becomes includeinCatalog and is catalog default 0 not sure how to deal with site specific fields like isSiteHosting Contensive Support Add fields to items as needed to support hosting Member Smart membership types become a child of include in catalog default 0 Ecommerce Methods / API There are two component of the api, native addon methods and a dotnet wrapper that calls the native methods. addon Interface all addon interface calls match the dotnet calls, with the function passed through a cmd argument. For example

cp.doc.setProperty( “method”, “createAccount” ) cp.doc.setProperty( “accountName”, “ACME Fireworks” ) result = cp.utils.executeAddon( ecommerceMethodsAddonGuid )

Performs the following:

result = createAccount( ‘ACME Fireworks’ )

getTransactions Returns a list of transactions for the account.

Arguments accountId: required dateFrom: optional. dateTo: optional.

Return: amount dateTrans description type: charge payment credit other

getChargesAndPayments Returns a list of account charges and payments that would typically be presented to an account as a statement.

Arguments accountId: required dateFrom: optional. dateTo: optional.

Return: amount dateTrans description type: invoice payment credit memo charge

getOpenOrderId Online orders only, browser must support cookies. Returns the current open order for this visitor, or for this user if they are authenticated. When an order is first created online, it is associated to the visit/visitor. At any point it can be converted to a user or account order with setOrderUser or setOrderAccount. Once converted, the order is only accessable online to the user, no longer to the account.

Arguments: none

Return: string, orderId or 0 if there is no open order

createAccount creates a new account, sets the account to the user and the user to the account. returns the accountId for the new account Name. The user must have an email address, and can not already have an accountid set.

Arguments userId: required the id of the initial billing and contact member. This person must have a blank accountId This person must have a valid email address accountName: optional. if provided, it is used. if not provided, the name of the user will be used. If blank, an account number will be set in the name.

Return: string, accountId or userErrorMessage

createOrder creates a new order. A user or an account must be set before the order can be completed (billed or paid)

If a user is assigned, the user’s account will be used. If an account is set, the billing contact will be set as the user.

Once a user has been set, online orders will no longer be trackable with visit or visitor.

Arguments: none

Return: string, orderId or userErrorMessage

addOrderItem adds an item to the order Arguments: orderId: required. itemId: required quantity: optional optionString: optional A string added to the order detail to specify item options userId: optional - if provided, this is the individual customer associated with this item purchase. Some items like subscriptions will put the customer in a group during fulfillment.

Return: string, orderDetailId

setOrderAccount assigns an account to an order, only if it currently is unassigned. An account is required before the order can be completed.

Arguments: orderId: required accountId: required

Return: empty

setOrderUser Assigns a user to an order, only if it currently is unassigned. An order requires a user before it can be completed.

Arguments: orderId: required userId: required

Return: empty

setOrderShipMethodId Sets the shipping method to be used for the order

Arguments: orderId: required shippingmethodId: required

Return: empty

getAccountPayMethod returns the pay method set on the account 0 = unknown 1 = no charge 2 = on Demand 3 = Bill 4 = Bill and Fulfill when paid

Arguments: acccountId: required

Return: string, numeric value

getAccountStatus returns the status of the account 0 = unknown 1 = open 2 = closed

Arguments: acccountId: required

Return: string, numeric value

calculateOrder calculates order tax, shipping, itemtotal, total based on itemdetails, etc. It is called by other methods. Call if the order, orderDetails, items, account, user are modified outside the ecommerce API.

Arguments: orderId: required

Return: true if success, else returns a message.

payOrder attempts to pay for the order with either a credit card or a specific onDemandMethod. The order may be complete or not-complete. (A complete order can not be modified). If the order pays OK, it is completed. Otherwise the order is not modified. If the payment fails, no customer notification is sent and no hold is put on the account. If their account has it enabled, the order receipt is sent.

Arguments: orderId: required paymentComment1: optional paymentComment2: optional shipFirstName,lastname,company,address,city,state,zip,country onDemandMethodId: if not 0, it must match an account payMethod for this account. if onDemandmethodId=0 then

CreditCardNumber: (required) CreditCardExpiration: (required) SecurityCode: (required) custFirstName ...LastName,Address,City,State,Zip,Country,Email

• • • • • CHANGE 1/19/2013

Return: boolean - true if processed OK argument returnUserError is “OK” or contains a user appropriate msg getInvoice Returns the invoice associated with the orderId

Arguments: orderId: required

Return: string

chargeOrder - charges to account using account pay method - returns true if success, else returns a message. - if the account is setup onDemand and the payment fails, no decline notice is sent and the account is not suspended (held for 3 days) Arguments: orderId: required paymentComment1: optional paymentComment2: optional shipFirstName,lastname,company,address,city,state,zip,country

paidOrder - marks an order paid - creates all charge and pay transactions - assumes caller accepted funds (maybe through paypal) - returns “OK” if success, else returns a message. Arguments: orderId: required paidBy: required, a string that describes how it was paid

billOrder - bills the order, but does not pay and does not fulfill - returns true if success, else returns a message. Arguments: orderId: required

billAndFulfillOrder - bills the order and calls fulfill. - returns true if success, else returns a message. Arguments: orderId: required

getOrderShipOptionSelect Returns an html select list of all options available to the order specified, based on the weight, charge, zipcode and country saved in the order.

Arguments: orderId: required htmlName: required - the name attribute of the html select htmlId: optional - the Id attribute of the html select htmlClass: optional - the class attribute of the html select

Return: string if no shipping options apply, a blank is returned

getShipOptionSelect Returns an html select list of all options available to the order specified, based on the weight, charge, zipcode and country arguments passed.

Arguments: orderId: required htmlName: required - the name attribute of the html select htmlId: optional - the Id attribute of the html select htmlClass: optional - the class attribute of the html select shipMethodId: integer, required - the method currently selected shipWeight: number, required - the weight in pounds itemCharget: number, required - the total of the items for this order shipZip: required, text - the zipcode of the shipping address shipCountry: required, text - the country of the shipping address

Return: string if no shipping options apply, a blank is returned

getShipCharge Returns the charge for shipping based on the arguments provided.

Arguments: shipMethodId: integer, required - the method currently selected shipWeight: number, required - the weight in pounds itemCharge: number, required - the total of the items for this order shipZip: required, text - the zipcode of the shipping address shipCountry: required, text - the country of the shipping address

Return: number

setAccountPayMethod Arguments: accountId: required payMethodId: required 0 = unknown 1 = no charge 2 = on Demand 3 = Bill and fulfill with paid 4 = Bill and fulfill immediately

setAccountPrimaryContact Arguments: accountId: required userId: required setAccountBillingContact Arguments: accountId: required userId: required addAccountOnDemandMethod adds an item to the order Arguments: accountId: required. CreditCardNumber: (required) CreditCardExpiration: (required) SecurityCode: (required) custFirstName ...LastName,Address,City,State,Zip,Country,Email Return: string, onDemandMethodId

setAccountOnDemandMethod Arguments: accountId: required onDemandMethodId: required

setAccountOnDemandMethodSecondary Arguments: accountId: required onDemandMethodId: required

getOnlinePaymentFields Returns all the credit card payment fields using the site’s payment configuration. Add these fields to a form, and when the form is submitted, call processCreditCardPaymentFields. The fields are read from document properties and the transaction is processed. These fields can be wrapped in an html form and submitted with a button, or submitted ajax.

This call must be made from an secure SSL document (page)

Arguments: none

Return: Html string

processOnlinePaymentFields Processes the fields created with getOnolinePaymentFields

Arguments: orderIdList: required - a comma delimited list of OrderId to be paid. returnUserError: if the method returns false, this string contains a message appropriate for the user to understand the issue. payComment1: optional payComment2: optional

Return: Boolean, true if the process is OK, false if there was an error. On error, the argument returnUserError contains a user appropriate explaination

Tables Accounts The account is the record that is charged. All transactions have to have an account to charge and be paid from.

tablename = abAccounts memberId ( Contact ) The person who is authorized to charge things against the account billingMemberId ( Billing Contact ) The person responsible for ensuring payment from the account closed (Closed) When true, this account can no longer be charged. payMethodId Lookup list below This represents the accounts preferred method of payment. 1 - House 2 - Credit Card 3 - Billing notificationMethodId Lookup list below. How the account would preferred being notified. 1 - Email 2 - Fax termsId Lookup into content “Account Terms”. This information provides credit terms for the account. dateHoldBillingUntil When not null, no payments can be run against this account until the date indicated. Charges should still accrue. dateLastBillingNotice This is the date of the last time the account was notificed about a balance due. requestedCancelDate After this date the account should not longer be charged. Services should be canceled on this date. referralCode When the account was created, if a code was used for tracking it is saved here. commissionAccountId If not null, commissions on payments to applicable charges are created in this account. emailCharges When checked, all charges to the account should be emailed to the billing contact. creditCardNumber creditCardName creditCardExpiration creditCardType creditCardCode Account Transactions Each entry represents either a credit or debit to the account. This will be considered an asset account so a charge increases and is a Debit, a payment decreases the balance and is a Credit.

tablename = abAccountTransactions Approved payment transactions -- shows the payment was approved. If false, the transactions is not valid isCharge If true, this is a charge transaction. A positive amount represents a charge to the account increases its balance due. A negative amount represents an adjustment that decreases the amount due. isCommission if true, this transaction is a result of a commission on a different transaction amount The amount of the transaction. Position amounts increase the balance due from the account. accountId The account being charged or paying. isSetupFee for charge transactions -- if true, this transaction is a one-time charge. If false, this transaction is a result of a recurring charge. orderId (old .invoiceId) Charge Transactions -- The order which originated the transaction dateDue Charge Transactions -- Determined by the pay method and set at the time of the charge. Any transaction unpaid after this date has passed is passed due. fromDate Charge Transactions -- When there is a service involved, the fromDate and toDate are the service dates. toDate Charge Transactions -- When there is a service involved, the fromDate and toDate are the service dates. recurringPurchaseId (old .accountDetaiId) Charge Transactions - When set, this charge was created by the associated entry in Recurring Purchases. paidByTransactionId Charge Transactions -- When set, this transaction was paid by the associated transaction. One payment can pay multiple charges. If a partial payment is made on a account, the charge must be broken up and each charge paid in full. paymentCheckNumber Payment Transactions -- The check number creditCardNumber Payment Transactions -- cc number creditCardAuthorization Payment Transactions -- authorizations from the payment processor authorizationMessage Payment Transactions -- message from the payment processor paymentAppliedToCharges Payment Transactions -- if true, this payment has been applied to charges. orderId For charge transactions, this is the order the created the transaction. Recurring Purchases (old Account Details) Each record represents a recurring purchase. The account billing process uses these records to create charge transactions periodically, which may then be paid. accountId The account to be charged itemId The item to use for purchase details discountAmount (old .customPeriodicFee) if provided, this amount will subtracted from the product amount when creating the charge transaction isCommissionable if checked, charges from this recurring purchase will be commissionable dateChargeStart When set, no charges will be created before this date. When a charge is created, it will never be back-charged earlier then this date. The effect is this will be the start date for the purchase, reguardless of other transactions. However, no refunds will be created based on this setting. dateChargeEnd When set, this represents the end of a contract period for a recurring purchase. This is generally the anticipated end of a longer purchase. For instance, this may be a monthly charge with a one year contract. The dateChargeEnd is the end of the year. It does not mean cancel, but represents the earliest time when the charge can be ended. The purchase will not be charge after this date. requestedCancelDate When set, this is the date after which the customer no longer wants the service. The purchase will not be charge after this date. referralId This is the ID of the referral record in referrals. canceled When true, this purchase no longer charges dateStart (dateJoin) This date is set to the date the purchase is created. dateChargedThrough This date, set by the recurring purchase process is the date that this purchase has been charged through. The recurring purchase process will create a new order based on this date. datePaidThrough This date is set by the payment process and manual payment entry. dateInactivate This is the date that the product should be deactivated for non-payment. dateCancel This is the date that the purchase is canceled for non-payment. Groups membershipControlled Contensive -- This is a developer-only field. When set, you can not add or remove anyone or delete the group.. The Member Tracking Process (MTP) will set the field when it creates the groups.

Referrals Is a list of codes created to track promotions and commissions. To use a referral, the customer enters a code which matches a referral record. The commissions and discounts then apply to only those items set in Referral Item Rules. referral.code The text code assigned to this referral. When entered during the purchase process, this referral is applied commissionAccountId When provided, this commission account will be used for the Order or Recurring Purchase. initialChargeDiscountAmount When provided, this discount amount will be applied to the initial purchase. recurringChargeDiscountAmount When provided, this discount amount will be applied to recurring purchases. recurringChargeDiscountPeriods When provided, the recurreint ChargeDiscountAmount only applies for this many periods. Account Notes Are a list of notes created the administrator. accountId The account associated with this note copy The text of the note. Account Terms The billing arrangements for accounts set to bill as pay method. daysToPay The number of days after the purchase date before the due date. Account Messages Are a list of messges created by the system to track activities. accountId The account associated with this note copy The text of the note. Items name copy overview sortOrder active hideOrderButton categoryId itemNumber UPC materials featured new viewings quantityOnHand quantityLow imageFilename thumbnailFilename options unitprice saleprice specialprice onSale allowReceiptCopy receiptCopy shippingRequired weight organizationId sourceitemNumber groupId The Subscription Group -- if this is not blank, anyone purchasing this item will be added to this group with the group expiration from groupExpirationPeriod and groupExpirationPeriodMonths groupExpirationPeriod This is an integer value in Days. it is used for both the expiration date of a subscription when it is purchased, and for the recurring billing period when a recurringCharge is included. groupExpirationPeriodMonths This is an integer value in Months, and acts like groupExpirationDays -- effecting both group expiration for subscriptions and the recurring purchase period. isInCatalog (new) default true. if true, this item appears in the catalog isCommissionable (new) default false. if true, the commissionaccountid receives thier commission on this item. For catalog purchases, the commission account is set when a new account is created with a referral code. recurringCharge (new) if not zero, this purchase creates a recurring purchase record which charges the account at the beginning of each period, based on the groupExpirationPeriod and groupExpirationPerodMonths. If the periods are zero, the recurring Charge is not valid. recurringPrebillDays(new) For a recurring item, how many days before the purchase date should it be invoiced. The Due date will still be the purchase date plus the days to pay (in account terms) Orders An order is created for all completed purchases. Processes may create incomplete orders as well. The line items of the order are orderdetails The completed order total is added to transactions as a purchase. Invoices sent represent a single orders. Name datePurchase The effective purchase date for the order. For orders invoiced in advance of the purchase, this is the date the purchase should take place. For instance, for a membership that expires on July 1, you might want to invoice for the renewal 30 days head of time. The datePurchase is July 1, the invoice date may be June 1, and if you extend them 10 days credit, the dueDate would be July 10. dateDue When the order should be paid specialPricing If true, this order qualified pricelevelFreeShipping if true, this order qualified itemCharge The total amount of all items shipCharge The calculated amount of shipping taxCharge The calculated amount of tax. priceLevelDiscount The calculated amount of the discount based on the price Level Discount scheme TotalCharge The total of item, ship, tax and discounts orderCompleted (can be removed and use dateComplete instead) - see orderComplete for details. readyForBatchComplete When true, the background batch will complete this order, performing all the billing, invoiceing and payment when necessary. dateCompleted Legacy - set when the order is paid. Current - set when the order is billed. -- however, there is a special case to cover the order upgrade. If dateComplete is set and ccNumber is set, the order is considered legacy and must be Paid. In this case, the payDate is set to the dateCompleted and paidByTransactionid is set to -1 to prevent re-paying. payMethod a text description of the pay method used payDate When the order was paid. For online orders this is populated. For offline payments, it is populated at the time the order is paid. ccAuthCode The code returned from the last payment process attempted. ccTypeActionCode The code returned from the last payment process attempted. ccRefCode The code returned from the last payment process attempted. billName

phone
fax

company address address2 city state zip country billConfirmed not sure shipDate date when order is shipping shipTracking tracking number from the shipper shipMethod textr field with the name of the ship method used shipWeight memberId visitorId visitId visitId orderDetails name a text description of the item name, quanitity and options orderId itemId itemNumber quantity options unitPrice weight sourceid groupMemberId The user Id of the person who will be given membership for items with a groupId. These are items that provide group membership when purchased. The userid is saved in the orderDetail record because the group membership is created when the purchase is completed, which may be by a manual payment long after the purchase is made. if the groupmemberid is not set, the account contact will be used. item Categories Order Ship Methods Item Materials item Material Categories Item Categories