Documentation You are here: start » v » 2.0 » emails

Table of Contents

Email Receipts

What's In an Email Receipt?

An example email receipt sent by FoxyCart using the default HTML Responsive template

FoxyCart's email receipts include almost everything in the web receipt, as well as any additional text you have configured in your receipt template(s). (You can see an example receipt to the right.) The major difference between the web receipt and the email receipts is that email receipts have specific sections that are only included in certain situations.

Email receipts for each transaction are sent to the customer by default. You can turn this off by going to the email receipt settings of the Foxy admin and removing the text from the receipt email subject setting. The email receipt will also not be sent to the store in this case.

Transaction Email Receipts

A “transaction email receipt” is what you'd probably consider to be a “normal” receipt. It's the main content section of a typical receipt, and will generally include the cart contents and transaction information (customer name, email, address, shipping info, etc.).

Important to note is that the default template will include a block of text (customizable in your store's language section) with subscription-specific links if a subscription is present in the cart. By default, these links will allow your customers to update their payment information or cancel their subscriptions straight from the email receipts they're already receiving. If you're doing recurring billing through FoxyCart we strongly recommend taking a look at that text, and running a few test orders.

The transaction email receipt will include everything that's part of the web-based receipt that is displayed to the customer after a successful transaction (in their web browser).

Subscription Cancellation Confirmation Email Receipts

Breaking up is hard to do, so FoxyCart allows for a customizable section to be included if (and only if) the email receipt is for a subscription cancellation. This will help you make it clear to the customer that their subscription has been set to cancel. These are sent only after a subscription has been successfully canceled through the checkout process. These emails will not send if a subscription is set to end or set to be inactive via the administration or the API.

"Update Info" Email Receipts

When a customer updates their information with the ''updateinfo'' flag, this section is included in the email receipt.

Who Gets Email Receipts?

The customer. If you have a “receipt email subject” configured in your store's “email” section, the customer will receive an email receipt for any transaction run on their account, including every time their account is billed for any recurring billing they have.

The store. If you have the “BCC store email address” checkbox checked in your store's “email” section, the store email address (as configured in your store settings) will receive a BCC copy of the email address. Note that this is a straight BCC copy, and looks identical to the customer's email receipt. If you're testing with an email address that goes to the same place as the store's email, you likely will only see one email receipt, since many mail servers would discard the extra copy as a duplicate.

Other addresses. If you'd like to send receipts to more than one person at your organization, just add additional emails to the “store email(s)” field in the “store settings” page in the admin. Separate emails by commas. You can also see the category specific email receipts section below for info on sending to other email addresses.

Default Templates and Customizations

The default HTML email receipt template is visible above at the right, but you can fully customize your email receipt much like you'd do with any other template on your store. If you're just looking to change language (such as the message that appears at the top or labels for sections) we'd suggest you start with making changes in the strings in the language section of your store's Foxy administration.

If you choose to alter the base templates in the email receipt settings, the big difference is that email formatting is stuck in the 1990s, so you'll want to brush up on HTML email formatting. CampaignMonitor has fantastic templates and resources for CSS support in HTML emails that we highly recommend.

As the Foxy email receipt templates handle a number of different emails beyond the normal transaction email receipt (including subscription reminders and cancellations), and the default styles are inlined in the HTML, it does make the template a bit more complex to customise. We know that can make them a bit imposing to work with, and are considering options of email editors that could potentially be integrated.

Here's some general tips for customising the email receipts beyond just language customisations:

  • We would recommend copying the HTML template out into a text editor for modification. One with syntax highlighting (and optionally with support for Twig template language) will make the template easier to work with.
  • If you're looking to use a completely different template from another service, you'll need to bring in the Twig logic to handle the different email types and outputting the customers information. There's also an overview at the bottom of this page with all the placeholders available to the email receipt.
  • If you need to reference the default HTML template at all, that's also available on Github here.

Category Specific Email Receipts

FoxyCart allows additional emails to be configured per category. The first option is to enable an additional customer email, which could be useful if a specific product category required extra information like conference registration information, special shipping or pickup information, or a request for additional information. The second option is for an additional admin email to be sent, which could be useful if sales of certain products need to notify specific departments within an organization.

You can add category emails in your categories here.

When Email Receipts are Sent

Email receipts are sent only in the following two situations:

  1. A customer places a successful order.
  2. A store administrator manually resends the email receipt from the “transactions” page in the store's admin.

Didn't Get an Email Receipt?

If you didn't receive an email receipt that you think you should have, please follow the steps below to ensure we've ruled out the common causes before you contact support.

  1. Check your spam folder. Though we have exceedingly high deliverability rates, and only send from clean IP addresses, it can happen.
  2. Reread the "Who Gets Email Receipts" section above, and double confirm that your customer email receipt isn't going to the same place as your store's BCC copy.
  3. Be sure that the email address actually exists and can accept mail. Quite often when we look into our mail logs we find that a mail server hasn't been set up or that the email address in question doesn't exist.
  4. Contact support, being sure to include the exact email address that isn't receiving emails.

How Emails Are Sent (SPF, DKIM, DMARC, etc.)

There are 3 ways Foxy can be configured to send emails on your store's behalf:

  1. Default: The email's From address is your store's configured email, but Foxy's address is the Return-Path (meaning we get the bounces), and we'll add a Sender header, so some mail clients may show a message that your email receipts are “on behalf of” or “sent via”. SPF and DKIM pass, but DMARC will fail. If you use DMARC on your domain, you'll need to do one of the following.
  2. Email DNS: This approach requires some DNS records to be added to your domain, and will allow us to avoid the “sender” header mentioned above. SPF and DKIM pass, and DMARC should pass.
  3. Bring Your Own SMTP: You can also configure your own SMTP server, and Foxy will simply use that. You're responsible for SPF, DKIM, and DMARC, but you may have more control and visibility (if you're using something like MailChimp Mandrill, Zoho ZeptoMail, PostmarkApp, etc.). Note that if there's a connection error, Foxy will fall back to the “default” option above.

More details about these options are below

Using FoxyCart's Mail Servers (Default)

By default, FoxyCart sends emails with extremely high deliverability rates, passing both SPF and DKIM standards. Though your configured email address will be in the From line of the email, we do use an @foxycart.com address in the Sender header, which can cause some mail clients (like Outlook and Hotmail) to display an “on behalf of” message when viewing the message details. Google does something similar by adding a “via” heading.

This default option is easy, reliable, and requires no additional work from you. But if you don't want the “on behalf of” or “via” text, OR if you're using DMARC, you must use one of the following options.

Some domains like @yahoo.com have strict DMARC policies, which prevent us from spoofing their emails. If you set your store email address to these domains (including aol.com, gmail.com, googlemail.com, hotmail.com, live.com, outlook.com, verizon.net, yahoo.ca, yahoo.com), we cannot use your configured email address as the From address, so we will send from a Foxy address, with your store's email as the Reply-To. This isn't great, so we recommend using an email at your own domain if you can.

Foxy's "Email DNS" Functionality

SPF and DKIM both use the Return-Path address (aka “mail from”, “bounce address”, “envelope header”) to validate, which is generally invisible to the recipient, which means an email could pass SPF and DKIM but the From address could be completely different. DMARC fixes this by relying on SPF or DKIM passing with a Return-Path address that matches the domain of the From address.

In order for Foxy to send email on your behalf using your domain in the envelope header, you'll need to add a few DNS records. Note also that in this situation we'll remove the Sender header, so there will be no “on behalf of” text in any clients. Our mail servers still handle everything for you, but without any Foxy-related email addresses showing anywhere.

To enable this, go to your “advanced” section in your FoxyCart admin and enable the “enable email DNS” checkbox. It may take a few hours after your DNS is updated for this to be enabled. You can contact support if you'd like a status update.

Record Type Subdomain Value
TXT smtpapi._domainkey 
k=rsa; t=s; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDPtW5iwpXVPiH5FzJ7Nrl8USzuY9zqqzjE0D1r04xDN6qwziDnmgcFNNfMewVKN2D1O+2J9N14hRprzByFwfQW76yojh54Xu3uSbQ3JP0A7k8o8GutRF8zbFUA8n0ZH2y0cIEjMliXY4W4LwPA7m4q0ObmvSjhd63O9d8z1XkUBwIDAQAB
TXT @ Add include:_spf.foxycart.com to your existing SPF record.

If you don't already have an SPF record on your domain, you will need to create one. While the details of creating an SPF record go beyond what we can provide here, you can generally pretty easily ask your web host for help, or Google for records to use. For example:

  • Help from Google Apps, if you use Google Apps for your mail
  • spf-record.com/generator, which may be very useful. In the second step, expand the “Advanced Settings” section and add _spf.foxycart.com in the “Delegate to external SPF record (include)” text area. Note the value for your SPF record will be the portion in the text input that they generate, beginning with v=spf1.

Using Your Own SMTP Server

If you'd like, you can configure FoxyCart to send email using your own SMTP credentials. You can enable it from the “advanced” settings page of your FoxyCart admin, within the “Email Receipt Settings” section labelled “Use your own smtp server”. A few things to note, if you go this route:

  • If our servers cannot make a connection to your SMTP server, we will failover to our normal email handling, as described in the section above. For that reason…
  • We recommend you configure the “email DNS”, so if/when FoxyCart does send mail on your behalf, it's a slightly more similar approach (and avoids the “via email.foxycart.com” language).

Email Receipt Placeholders

Customizing the email receipts is much like customizing any other template, but there are a few email-specific values that can be customized to change the email behavior. These values should be set under the “email receipt” settings in the receipt text email template, at the top of the text area. This applies whether or not you're using the HTML version. You may need to select the “Custom Text Template” option to get this text box to appear.

Note that the Twig variables available in the “receipt email subject:” setting are very limited, and so if you need to access a variable such as the customer's first name, you'll need to make the customization within the “receipt text email template:” text area rather than the “receipt email subject:” field.

Here are some email-specific values that can be customized:

  • email_subject: Can be used to set the email subject. If set to an empty string, the email will not be sent.
  • email_from: Can be used to set the email's from header.
  • email_replyto: Can be used to set the email's reply-to header.
  • email_bcc: Can be used to set the email's bcc addresses, comma separated. So if you want to BCC an address conditionally (based on country, cart contents, whatever), you can. The “bcc store email address” option needs to be enabled in your email settings to customise, and whatever it is set to in Twig will overwrite the store emails it would normally BCC to.

You'd set these using Twig and a custom fc_output_data filter, like this: 

{% set custom_subject = 'custom email subject for order ' ~ order_id ~ ' shipping to ' ~ shipping_address.first_name %}
{{ custom_subject|fc_output_data('email_subject') }}
 
{% set custom_from = 'someone@example.com' %}
{{ custom_from|fc_output_data('email_from') }}
 
{% set custom_bcc = 'someone_else@example.com' %}
{{ custom_bcc|fc_output_data('email_bcc') }}

Full List of All Placeholders

FoxyCart uses twig and twig.js as a template language so you can completely customize everything about your checkout experience. Listed below is all the data which is exposed to the templates and also available in JavaScript in the FC.json variable.

When outputting in the template, you would utilise Twig, like {{ variablename }}. Note that if you're looking to access data that is within arrays (such as items, or item options), then you need to access those within a for loop in the Twig, like: 

{% for item in items %}
  {{ item.name }}
{% endfor %}

Note that the data is broken into different sections by the page scope it's available on. The cart is available on all pages (as it is present on all pages), but there are some strings that are specific to just other pages like the checkout and receipt.

Cart

cart_cancel_and_continue_link
Description: URL for continuing back to the store from the cart.
cart_config_hash
Description: Used to validate the locale storage version of FC.json.config is up to date.
cart_is_fullpage
Description: true or false depending if the cart is the full page cart or not
context
Description: Either cart, checkout or receipt. Used for configuring various display and functionality concerns. cart represents both Sidecart and full page cart versions.
coupons
coupons.{coupon_code}
coupons.{coupon_code}.amount
coupons.{coupon_code}.id
coupons.{coupon_code}.is_applied
coupons.{coupon_code}.is_taxable
coupons.{coupon_code}.name
Description: Coupons associated with this cart. The {coupon_code} is the code value used by the customer to add the coupon.
Note: If the cart features codes that are shared between multiple coupons (for coupons that have the “Shared Codes Allowed?” checkbox checked), these coupons will become a nested array of coupons, with the {coupon_code} still as the key. The attributes within each array item will still be the same amount, id, is_applied, is_taxable and name.
"coupons": {
    "code1a": {
        "amount": -1,
        "id": "4704984",
        "is_applied": true,
        "is_taxable": false,
        "name": "Coupon 2"
    },
    "code2a": [
        {
            "amount": -1,
            "id": "4704985",
            "is_applied": true,
            "is_taxable": false,
            "name": "Coupon 1"
        },
        {
            "amount": -1,
            "id": "4704988",
            "is_applied": true,
            "is_taxable": false,
            "name": "Coupon 2"
        }
    ]
}
custom_fields
custom_fields.{name}
custom_fields.{name}.is_hidden
custom_fields.{name}.value
Description: The custom fields associated with this transaction. The is_hidden bit will be true if the custom fields were passed in via the h: prefix. The {name} is the value of the name assigned to this custom field.
expires_in
Description: The time in seconds until the first product in the cart expires
future_coupons
future_coupons.{coupon_code}
future_coupons.{coupon_code}.amount
future_coupons.{coupon_code}.id
future_coupons.{coupon_code}.is_applied
future_coupons.{coupon_code}.name
Description: Same as coupons above, but for products with a start date or next transaction date in the future.
future_subscription_totals_by_date
future_subscription_totals_by_date.total
future_subscription_totals_by_date.total_item_price
future_subscription_totals_by_date.total_shipping
future_subscription_totals_by_date.total_tax
future_subscription_totals_by_date.total_weight
Description: The totals for subscription products with a start date or next transaction date in the are grouped together here for the cart display.
gift_cards
gift_cards.{gift_card_code}
gift_cards.{gift_card_code}.amount
gift_cards.{gift_card_code}.id
gift_cards.{gift_card_code}.code_id
gift_cards.{gift_card_code}.is_applied
gift_cards.{gift_card_code}.name
gift_cards.{gift_card_code}.current_balance
Description: Gift cards associated with this cart. The {gift_card_code} is the code value used by the customer to add the gift card.
Note: The current_balance attribute will not factor in the discount that could apply from the cart or checkout. On the web receipt, current_balance will take into account the discount from that transaction, and any other uses of the gift card since then (if the receipt is being revisited). The email receipt will be the current balance of the gift card at the time the transaction was completed.
has_eligible_coupons
Description: If the cart contains products which can have a coupon applied to them.
has_future_products
Description: If the cart contains products with a start date or a next transaction in the future (a “future product”).
has_future_shipping
Description: If the cart contains future products from categories which support shipping.
has_live_rate_shippable_products
Description: If the cart contains products from categories which support live shipping rates.
has_location_dependant_taxes
Description: If the cart contains products from categories which have taxes based on the customer's location. This is used for handling third party payment options such as PayPal Express and Amazon FPS.
has_multiship
Description: If the store has multiship turned on.
has_product_images
Description: If any of the products in the cart took advantage of the image option.
has_shippable_products
Description: If the cart contains products from categories which support shipping.
has_subscriptions
Description: If the cart contains subscription products.
has_taxes
Description: If the cart contains products from categories which have taxes applied to them.
is_future_shipping_only
Description: If all of the products in the cart are future products, this tells the system the shipping calculations will only be for future products.
is_new_subscription
Description: If the cart contains a new subscription
is_subscription_cancel
Description: If this transaction is for canceling an existing active subscription.
is_subscription_modification
Description: If this transaction is currently modifying an existing active subscription. This will usually mean there are products in the cart which will charge in the future.
is_updateinfo
Description: If cart=updateinfo.
item_count
Description: The sum total of all the product quantities in the cart.
items[]
Description: An array of all the products in the cart.
items[].alt_name
Used in the alt attribute of the product link.
items[].base_price
Product price before product option modifiers.
items[].category
Product category code.
items[].code
Product code or sku.
items[].parent_code
Parent product code or sku.
items[].delivery_type
The delivery type of this product.
items[].downloadable_id
If this product is a downloadable, this is the downloadable id for it.
items[].expires
The timestamp for when this product expires.
items[].height
Reserved for future use.
items[].id
Unique internal id for this product.
items[].image
The image url for this product.
items[].is_parent
If this product is a parent product or not
items[].item_number
Used for organizing item display and managing the product update process.
items[].length
Reserved for future use.
items[].multiship
The multiship group number used for organizing products into shipments.
items[].name
The product name.
items[].options[]
Description: Array or product options for this product.
items[].options[].class
The option name stripped of anything but letters, numbers, dashes and underscores so it can be used as a html class attribute.
items[].options[].name
The product option name.
items[].options[].value
The product option value.
items[].price
The price extension of these products (price_each * quantity)
items[].price_each
The actual price of an individual product after product option modifiers.
items[].quantity
The quantity of this product in the cart.
items[].quantity_max
The maximum quantity allowed in the cart for this product.
items[].quantity_min
The minimum quantity allowed in the cart for this product.
items[].shipto
The shipto name of this product used for multiship.
items[].sub_enddate
The end date of this subscription product.
items[].sub_frequency
The frequency of this subscription product.
items[].sub_nextdate
The next date this subscription product will process.
items[].sub_startdate
The start date of this subscription product.
items[].url
The url of this product.
items[].weight
The weight extension of the this product (weight_each * quantity)
items[].weight_each
The weight of an individual product.
items[].width
Reserved for future use.
language
Description: The English name for the language of the cart as set by the template set (like english, french, german etc). Can be blank if using the default template set.
language_iso_code
Description: The 2 character ISO code for the language of the cart as set by the template set (like en, fr, de etc). Can be blank if using the default template set.
loading_coupons
loading_quantity
loading_shipping_results
loading_taxes
Description: Used for determining if a loading animation should currently be displayed.
locale_code
Description: The locale code for this cart such as en_US
locale_info
Description: This includes all of the data output by PHP's localeconv() including currency symbols, decimal point character, and thousands separator.
messages
Description: Used for displaying error, warning, and information messages in the cart.
messages.errors[]
Description: An array of error messages.
messages.errors[].context
The context of this error message which often relates to a form input.
messages.errors[].message
The content of the error message. Often times this will be blank as the error message is directly part of the template as a language string.
messages.info[]
Description: An array of informational messages.
messages.info[].context
The context of this informational message.
messages.info[].message
The content of the informational message.
messages.warnings[]
Description: An array of warning messages.
messages.warnings[].context
The context of this warning message.
messages.warnings[].message
The content of this warning message.
multiship_data
Description: (Currently empty for the cart, may be added in the future)
payment_info_required
Description: True if payment information is required for this transaction (order total > 0 for an order and not doing a subscription cancel).
session_id
Description: The session id of this cart.
session_name
Description: The name of the FoxyCart session.
shipping_address
Description: Container for the shipping address information.
shipping_address.address1
Address 1
shipping_address.address2
Address 2
shipping_address.address_name
The address name of this address (used mainly for multiship)
shipping_address.city
City
shipping_address.city_option_selected
The city, region put togther as a string used in the select option.
shipping_address.city_options
Description: Array of options returned from the postal code lookup.
shipping_address.city_options.city
City
shipping_address.city_options.region
Region (such as state or province)
shipping_address.company
Company
shipping_address.country
Two character country code
shipping_address.country_name
Country name
shipping_address.first_name
First Name
shipping_address.last_name
Last Name
shipping_address.phone
Phone
shipping_address.postal_code
Postal code
shipping_address.prefix
Prefix (used for multiship)
shipping_address.region
State or Province code
shipping_address.region_label
Label for this region (such as state or province)
shipping_address.region_name
State or province name.
shipping_address.shipping_results[]
Description: A result of calculating live shipping rates.
shipping_address.shipping_results[].method
This shipping method (USPS, UPS, FedEx, etc).
shipping_address.shipping_results[].price
The quoted price for this shipping service.
shipping_address.shipping_results[].service_id
The service id used by this shipping method for this service.
shipping_address.shipping_results[].service_name
The name of this shipping service.
shipping_address.shipping_service_description
The description of this shipping service.
shipping_address.shipping_service_id
The shipping service id the service the customer selected.
shipping_address.taxes[]
Description: An array of taxes associated with this shipping address.
shipping_address.taxes[].amount
Amount of this tax.
shipping_address.taxes[].applies_to_handling
Whether or not this tax applies to handling fees.
shipping_address.taxes[].applies_to_shipping
Whether or not this tax applies to shipping costs.
shipping_address.taxes[].default_amount
The default amount before being applied to a specific location.
shipping_address.taxes[].is_error
If this tax has an error.
shipping_address.taxes[].is_live
If this tax is live.
shipping_address.taxes[].name
The name of this tax.
shipping_address.taxes[].rate
The tax rate.
shipping_address.taxes[].tax_id
The internal id of this tax.
shipping_address.total_future_shipping
The total amount of future shipping costs for the products being sent to this address.
shipping_address.total_shipping
The total shipping costs for the products being sent to this address.
shipping_address.total_tax
The total tax for the products being sent to this address.
shipping_address.type
The type for this address (either billing or shipping)
shipping_and_handling_label
Description: The label describing the shipping applied to this order.
show_address_entry
Description: Used to determine if the cart address entry form should be displayed.
show_amazon_fps_payment_option
Description: Used for determining if the amazon payment button should be shown. It will not be shown if there are subscriptions in the cart.
show_coupon_input_button
Description: Used for determining if the coupon input button should be shown.
show_multiship_details
Description: Used to toggle the multiship details.
show_paypal_express_payment_option
Description: Used for determining if the Paypal payment button should be shown.
show_shipping_tbd
Description: Used for determining if live shipping rates haven't yet been calculated so a “TBD” indicator is displayed instead.
store_id
Description: The FoxyCart store id for this store.
template_set
Description: The code for the cart's current template set
total_discount
Description: The total coupon discount applied to this transaction.
total_future_item_price
Description: The total price of the future items in the cart.
total_future_shipping
Description: The total amount of the shipping costs assigned to future products in the cart.
total_future_weight_shippable
Description: The total weight of the future shipable products in the cart.
total_item_price
Description: The total price of the items in the cart.
total_order
Description: The order total
total_shipping
Description: The shipping total
total_tax
Description: The tax total
total_weight
Description: The total product weight.
total_weight_shippable
Description: The total weight of the shippable products in the cart.
transaction_id
Description: The FoxyCart transaction id for the contents of the cart.

Cart Config (FC.json.config)

cache_path
Description: Path used for caching images in the FoxyCart system.
cart_config_hash
Description: Used to validate the locale storage version of FC.json.config is up to date.
cdn_base_path
Description: The base path of your store's files served via the CDN.
cdn_static_path
Description: The base path of static files served via the CDN.
css_file
Description: The full path to the versioned store-specific stylesheet served by the CDN.
currency_format
Description: The currency format configured for your store and use for twig money formatting.
lang
Description: All language strings in FoxyCart are completely customizable. We start with a base language configuration and then you can customize them individually from there.
lang.{code}
lang.{code}…
Description: You can view all language strings used on the cart by viewing FC.json.config.lang in your browser's web console.
locations
Description: A complete listing of all valid country codes and state/provinces within those countries used by our find-as-you type auto complete (FoxyComplete) country and region lookup system.
locations.{country_code}
locations.{country_code}…
Description: Locations are grouped by their 2 character ISO country code.
locations.{country_code}.active
If this country is actively being used by the FoxyComplete system.
locations.{country_code}.alt
Alternative spellings or local spellings of this location name.
locations.{country_code}.boost
Used to give certain spellings a boost over others.
locations.{country_code}.cc2
ISO 3166-1 alpha-2 code for this country.
locations.{country_code}.cc3
ISO 3166-1 alpha-3 code for this country.
locations.{country_code}.ccnum
ISO 3166-1 numeric code for this country.
locations.{country_code}.cn
Country name (currently in english).
locations.{country_code}.pc
Description: Postal Code format details.
locations.{country_code}.pc.int
If the postal code is numeric only.
locations.{country_code}.pc.lang
The language key string for the description of this postal code.
locations.{country_code}.pc.regex
The regex pattern this postal code fits in for validation purposes.
locations.{country_code}.pc.req
Whether or not the postal code is required.
locations.{country_code}.pc.search
Whether or not this country supports a postal-code based search.
locations.{country_code}.r
Description: Region details for this country.
locations.{country_code}.r.lang
The language key string for name of this country's regions such as “state.”
locations.{country_code}.r.options.{region code}
Description: Region information organized by two character ISO code.
locations.{country_code}.r.options.{region code}.active
If this region is actively being used by the FoxyComplete system.
locations.{country_code}.r.options.{region code}.alt
Alternative spellings or local spellings of this region name.
locations.{country_code}.r.options.{region code}.boost
Used to give certain spellings a boost over others.
locations.{country_code}.r.options.{region code}.c
ISO 3166-1 alpha-2 code for this country.
locations.{country_code}.r.options.{region code}.n
Region name (currently in english).
locations.{country_code}.r.options.{region code}.req
If regions are required for this country.
locations_billing
Description: Locations used for billing address information only (see locations)
locations_shipping
Description: Locations used for shipping address information only (see locations)
paypal_checkout_button_url
Description: Locale specific PayPal payment button URL.
post_url
Description: URL for posting cart and checkout forms.
store_domain
Description: This FoxyCart stores FoxyCart store domain (the example part of example.foxycart.com).
store_logo_url
Description: Your store logo url as configured in the FoxyCart admin.
store_name
Description: Your FoxyCart store name as configured in the FoxyCart admin.
store_url
Description: Your store's website URL as configured in the FoxyCart admin.
template_config
Description: All of the settings configured in the FoxyCart admin under the configuration menu will be available here for you to use within your twig template customizations.
template_config.analytics_config
Description: (UNDER CONSTRUCTION): A place to automatically configure your analytics tools.
template_config.analytics_config.google_analytics
Description: Configuration settings for your Google Analytics account.
template_config.analytics_config.google_analytics.account_id
Your Google Analytics acccount id
template_config.analytics_config.google_analytics.account_key
Your Google Analytics acccount key
template_config.analytics_config.google_analytics.usage
Configuration for how this setting is being used.
template_config.analytics_config.segment_io
Description: Configuration settings for your Segment.io account.
template_config.analytics_config.segment_io.account_key
Your Segment.io acccount key
template_config.analytics_config.segment_io.usage
Configuration for how this setting is being used.
template_config.analytics_config.usage
Configuration for how this setting is being used.
template_config.cart_display_config
Description: Settings for controlling the display details of your cart.
template_config.cart_display_config.show_product_category
Whether or not to show the product category code in the line item details.
template_config.cart_display_config.show_product_code
Whether or not to show the product code in the line item details.
template_config.cart_display_config.show_product_options
Whether or not to show the product options in the line item details.
template_config.cart_display_config.show_product_weight
Whether or not to show the product weight in the line item details.
template_config.cart_display_config.usage
Whether or not the cart display config has been set or if defaults are in use.
template_config.checkout_type
Description: Either default_account, default_guest, guest_only, or account_only for determing if your checkout will accept guest checkouts or required named accounts and which one will be the default action.
template_config.colors
Description: This configuration allows you to specify the main colors of your website and our system will adjust the CSS using SASS as needed to incorporate your colors into our template designs.
template_config.colors.primary
colors.secondary
colors.tertiary
The primary, secondary, and tertiary colors for your website.
template_config.colors.usage
Whether or not this configuration setting is being used.
template_config.csc_requirements
Description: Settings for how you'd like to require the Card Security Code (CSC) for your website. Values include all_cards, sso_only (Single Sign On only), new_cards_only (do not require for saved cards).
template_config.custom_checkout_field_requirements
Description: Configuration for displaying and requiring various checkout fields and features.
template_config.custom_checkout_field_requirements.billing_address1
template_config.custom_checkout_field_requirements.billing_address2
template_config.custom_checkout_field_requirements.billing_city
template_config.custom_checkout_field_requirements.billing_company
template_config.custom_checkout_field_requirements.billing_country
template_config.custom_checkout_field_requirements.billing_first_name
template_config.custom_checkout_field_requirements.billing_last_name
template_config.custom_checkout_field_requirements.billing_phone
template_config.custom_checkout_field_requirements.billing_postal_code
template_config.custom_checkout_field_requirements.billing_region
These can be set to either hidden, required, optional, or default (in the case of billing_region)
template_config.custom_checkout_field_requirements.cart_controls
Whether or not to allow cart controls on the checkout page.
template_config.custom_checkout_field_requirements.coupon_entry
Whether or not to allow the coupon entry form on the checkout page.
template_config.custom_config
Description: This is where you can put your own custom configuration values for your twig templates. This might be helpful if you want to hard code your templates with some logic and change the display outcome by just adjusting the values here.
template_config.custom_script_values
Description: Used for setting custom JavaScript or CSS elements to be used in the default template.
template_config.custom_script_values.footer
If you have custom JavaScript you'd like to add above the </body> tag for your cart, checkout and receipt templates, put that here. You can use it for conversion tracking scripts by checking the first_receipt_display variable. Full twig syntax is supported here.
template_config.custom_script_values.header
If you have custom CSS (or JavaScript, though the footer is a better place for that) you'd like to add to the <head> tag for your cart, checkout and receipt templates, put that here. Full twig syntax is supported here.
template_config.custom_script_values.checkout_fields
If you to add custom fields to your store's checkout template, add HTML here. These will be inside the <form> tag on the checkout page and will submit with the rest of the checkout form and be recorded as custom fields on the transaction. Full twig syntax is supported here.
template_config.debug
Description: Turn this on to see debugging output in your web browser's console log.
template_config.debug.usage
How this setting is currently being used.
template_config.foxycomplete
Description: Our country and region auto completion system which lets users find locations as they type instead of having to select from a huge list of options.
template_config.foxycomplete.combobox_close
The icon used for closing the location combo box.
template_config.foxycomplete.combobox_open
The icon used for opening the location combo box.
template_config.foxycomplete.show_combobox
Whether or not to show the location combo box.
template_config.foxycomplete.show_flags
Whether or not to show the country flags.
template_config.foxycomplete.usage
Configure how this feature is being used.
template_config.newsletter_subscribe
Description: This allows you to easily add a “Subscribe Me” checkbox to your checkout template so you can use that value as a custom field in the transaction datafeed later.
template_config.newsletter_subscribe.usage
How this setting is configured.
template_config.ssl_receipt
Description: If you require the receipt page to be loaded over HTTPS, turn this feature on.
template_config.supported_payment_cards
Description: An array of the accepted payment cards by your store such as Visa, MasterCard, etc. This will control which card logos are shown on the checkout page.
template_config.tos_checkbox_settings
Description: Use this setting to easily add a terms of service checkbox to your checkout page.
template_config.tos_checkbox_settings.initial_state
Whether or not the terms of service checkbox is checked by default.
template_config.tos_checkbox_settings.url
The URL to your terms of service document.
template_config.tos_checkbox_settings.usage
How this setting is configured (none, required or optional).
template_config.use_checkout_confirmation_window
Description: (UNDER CONSTRUCTION) A popup window for customers to confirm their order before submitting it.
template_config.use_checkout_confirmation_window.usage
Configure how this feature is being used.
weight_uom
Description: The unit of measure used for calculating shipping weights.
with_controls
Description: Whether or not the current display output includes cart controls such as quantity and coupon entry fields.

Checkout

The checkout view data in FC.json includes everything in the cart including the following values:

anonymous_checkout_selected
Description: Used for determing if a customer opted to check out anonymously.
auth_token_is_valid
Description: Used for determining if the Single Sign On (SSO) authorization token is valid.
authentication_is_in_progress
Description: If the customer is currently authenticating.
authentication_is_not_successful
Description: If customer authentication failed.
authentication_is_successful
Description: If customer authentication is successful.
billing_address
Description: (See cart shipping_address)
cc_cvv2
Description: Credit card Card Security Code for new cards.
cc_cvv2_saved
Description: Credit card Card Security Code for existing cards.
cc_exp_month
Description: Credit card expiration date month.
cc_exp_year
Description: Credit card expiration date year.
cc_number
Description: Credit card number.
cc_number_masked
Description: Masked credit card number.
cc_type
Description: Credit card type (Visa, MasterCard, Amex, etc)
change_password
Description: If the customer as opted to change their password.
checkout_date
Description: The date this checkout took place.
checkout_type
Description: The type of checkout taking place which can be either default_account, default_guest, guest_only, account_only
continue_url
Description: The URL used on the receipt to continue back to your store's website.
create_account
Description: Whether or not the customer chose to create an account during checkout.
customer_email
Description: The customer email address.
customer_id_encoded
Description: Used for determining which customer just logged in.
customer_is_authenticated
Description: Used for determining if the current customer is authenticated via Single Sign On (SSO).
customer_password
Description: The customer password entered by the user.
email_is_checking
Description: If the checkout is currently checking to see if the email address given belongs to an existing customer.
email_is_found
Description: Indicates if the email address given belongs to an existing customer.
email_is_valid
Description: Indicates if the email address given is valid.
fc_auth_token
Description: The Single Sign On (SSO) authentication token.
fc_customer_id
Description: The Single Sign On (SSO) passed in customer id.
first_receipt_display
Description: If the receipt is being displayed for the very first time which can be helpful for displaying specific conversion tracking code.
force_password_reset
Description: If the customer requires a password reset because they logged in with a temporary password.
force_saved_account
Description: If the cart contains subscriptions, the customer will be forced to checkout as a named account.
geoip
Description: Used in the emails sent to store administrators to display the GEO IP lookup details for the country based on the ip address of the customer checking out. This will not be available for the checkout or receipt context.
has_discounts
Description: If the cart contains coupon discounts.
has_downloadables
Description: If the cart contains downloadable products.
has_saved_cc
Description: If the customer has a saved credit card.
has_visible_custom_fields
Description: If the checkout has custom fields which are not hidden custom fields.
hosted_payment_gateways
Description: Array of hosted payment gateways available for this checkout.
hosted_payment_gateways.lang_pay_with
Language and logo used on the checkout page to tell the customer they can pay with this method.
hosted_payment_gateways.lang_payment_method
Additional information for the customer indicating what happens next, such as if they will be redirected to another site to confirm payment.
hosted_payment_gateways.supports_subscriptions
Wehther or not this hosted payment method supports subscriptions.
hosted_payment_gateways.type
The type of this hosted solution such as bitpay, dwolla, etc.
html_downloadable_links
Description: The links for downloading products purchased as FoxyCart downloadables.
ip_address
Description: The ip address of the customer.
is_anonymous
Description: If the customer checked out as an anonymous user.
is_uoe
Description: If the customer is currently logged in using Unified Order Entry.
loading_submit
Description: Used for determining if an animation should be displayed near the submit button.
multiship_data
Description: Array of shipments for each multiship customer shipment (in additiona to address data found in shipping_address)
multiship_data.address_name
The name given to this shipto address. This will be the same as the “shipto” value in the cart.
multiship_data.checkout_total_tax
The tax total for this shipment used during checkout.
multiship_data.custom_fields
Custom fields for this shipment.
multiship_data.has_live_rate_shippable_products
Whether or not this shipment has products from a category which uses live shipping rates.
multiship_data.has_shipping_or_handling_cost
Whether or not this shipment has products from a category which has any shipping or handling costs.
multiship_data.has_visible_custom_fields
Whether or not any of the custom fields in this shipment are visable.
multiship_data.number
The shipto number used for visual organization.
multiship_data.total_future_shipping
The total future shipping amount in this shipment
multiship_data.total_item_price
The total amount of all the items in this shipment
multiship_data.total_price
The total price in this shipment
multiship_data.total_shipping
The total shipping amount in this shipment
multiship_data.total_tax
The total tax amount in this shipment
new_customer_password
Description: When creating a new customer or changing an existing password, this will contain the new password entered by the customer.
order_id
Description: The transaction id of this order.
password_expired
Description: True if the password this customer used has expired, such as when using a temporary password.
payer_id
Description: Used by 3D Secure systems.
payment_is_pending
Description: If the customer checked out with a hosted gateway which first marks the payment as pending, this boolean can be used for special messaging to the customer on the receipt.
payment_method_type
Description: Either plastic_saved, plastic_new, or the type of the hosted payment gateway being used.
payment_type
Description: The payment type usually being plastic, hosted (as in a hosted payment gateway), purchase_order, paypal or other.
processor_response
Description: The payment gateway response value used on the receipt.
purchase_order
Description: The purchase order value submitted by the customer.
receipt_url
Description: The connonical url of the transaction receipt.
required_fields
Description: Array of required field names as configured in the FoxyCart admin template configuration page.
shipping_and_handling_label
Description: The default label for the shipping and/or handling fees charged for this order.
show_message_for_testing
Description: Used to indicate if a testing informational message is to be displayed. This can be useful for styling purposes and can be triggered by passing in a fc_show_info custom field.
status
Description: Used in some situations such as with hosted gateways to specify the status of the current transaction. Values include approved, authorized, declined, pending, or rejected.
subscriptions
Description: Array of subscription data for this transaction.
subscriptions.description
The textual description of this subscription including the frequency.
subscriptions.sub_token_url
The subscription token url which can be used by the customer to modify or cancel this subscription or by the store to adjust the subscription via the API.
subscriptions.html_links
The links needed by the customer to modify or cancel this subscription in html format.
subscriptions.text_links
The links needed by the customer to modify or cancel this subscription in text format.
temporary_password_sent
Description: Indicating of the temporary password has been sent to the customer.
text_downloadable_links
Description: Text links for downloading the products purchased.
timestamp
Description: Used by the Single Sign On (SSO) feature to ensure the token is only valid for a specific amount of time.
token
Description: Used by 3D Secure systems.
tos_agreement
Description: The state of the terms of service checkbox, if being used by the checkout.
use_alternate_shipping_address
Description: A boolean state of the checkbox for using an alternate shipping address other than the billing address.
use_different_addresses
Description: The state of the checkbox for using an alternate shipping address other than the billing address.
utils
Description: Custom twig macros we've added which we've also ported to twig.js
utils.get_error_string
Get a specific error string from the array of errors by context key.
utils.get_info_string
Get a specific info string from the array of informational strings by context key.
utils.shipping_results
Macro for formatting shipping rate results into radio buttons.
utils.use_different_addresses
Macro for displaying the use alternate address checkbox.

Checkout Config (FC.json.config)

The checkout config view data in FC.json.config includes everything in the cart including the following values:

alert_test_gateway
Description: Used for FoxyCart test stores.
base_directory
Description: Used for determing the correct base directory for this store version.
cc_expiration_months
Description: An array of months for displaying the credit card expiration month select box.
cc_expiration_years
Description: An array of years for displaying the credit card expiration year select box.
has_multiple_payment_options
Description: A boolean used for display logic when there are more than one payment options enabled by the store for the checkout page.
lang
Description: Includes language strings from cart config lang as well as additional strings for checkout, email and receipt contexts.
supports_pay_with_plastic
Description: A boolean used for display logic on the checkout page for if the store supports paying with a debit or credit card.
supports_purchase_order
Description: A boolean used for dispaly logic on the checkout page for if the store supports paying by purchase order.

Email

The email view data in FC.json.config includes everything in the cart and checkout including the following values:

days_since_first_failed_transaction
Description: The number of days since the subscription in this email first failed, used for dunning reminder emails.
is_order
Description: If this email is for a normal transaction
is_expiring_payment_reminder
Description: If this email is for an expiring payment methods reminder email triggered by the dunning functionality
is_subscription_dunning_cancellation
Description: If this email is for a subscription that has just been cancelled through the dunning functionality
is_subscription_dunning_reminder
Description: If this email is for a subscription past due reminder email triggered by the dunning functionality

Page Tools

Site Tools