store
Collection: stores
A FoxyCart Store is your home for managing your online payment system as it relates to FoxyCart's platform. One store is used per organization selling online. You can create a store for free and use it until you are ready to collect live payments from your customers. We also recommend setting up a development store along with your production store so you can test out new features. Before you create a store, you must create a client and a user. When creating a store, you will get a response back containing an OAuth token giving you access to the store.
As part of security protections against abuse, an hCaptcha header is required as part of store creation. It is passed through a h-captcha-code header with the POST request to create a store. If you have a need to create stores as part of a platform integration, please get in touch with our support team to discuss this requirement further.
If you create custom attributes for your store, they will automatically be included in the response as embedded resources without having to zoom in on them.
Notes
The smtp_config value should be a JSON string containing the following fields:
- username: Your SMTP server username
- password: Your SMTP server password
- host: Your SMTP server host
- port: Your SMTP server port
- security: If your server requires a secure connection, use "ssl" or "tls". Can also be blank.
The custom_display_id_config value is a JSON object containing the following fields:
- enabled: A boolean, true or false.
- start: The starting value for your custom order id display such as 1.
- length: The minimum total length of the auto-incrementing part of the display ID.
- prefix: The prefix you would like your custom display id to begin with.
- suffix: The suffix you would like your custom display id to end with.
Inside custom_display_id_config you can also include a transaction_journal_entries node:
- enabled: A boolean, true or false.
- transaction_separator: Separator between transaction id and transaction action. String, max length 10.
- log_detail_request_types: JSON object with prefixes for every transaction action. Allowed actions are transaction_authcapture, transaction_refund, transaction_capture, transaction_void. Each contains a prefix string.
The features value should be a JSON object containing the following fields:
- allow_transaction_editing: Allows merchants to capture/void/refund transactions and edit completed transactions. A boolean, true or false.
The webhook_key can be either a single string key or a JSON object with the keys cart_signing, sso, api_legacy, and xml_datafeed. Whether set as a string or as separate keys in a JSON object, each key cannot be more than 100 characters.
Required Scopes
store_full_access stores_read stores_write Actions
Properties (46)
store_version_uri String This is the store version for this store. For more details about this version, see the store_versions property helpers which include changelog information.
Default: the latest version if not provided
store_name String · Required · max 100 The name of your store as you'd like it displayed to your customers and our system.
store_domain String · Required · max 50 This is a unique FoxyCart subdomain for your cart, checkout, and receipt. If you install a custom SSL certificate, this will contain a full domain such as store.yourdomain.com.
use_remote_domain Boolean Set to true when you plan to use a custom SSL certificate. If set to true, your store_domain must be a full domain.
store_url String · Required · max 300 The URL of your online store.
receipt_continue_url String · max 300 By default, FoxyCart sends customers back to the page referrer after completing a purchase. Instead, you can set a specific URL here.
store_email String · Required · max 300 This is the email address of your store. By default, this will be the from address for your store receipts. If you specify a from_email, you can also put in multiple email addresses here, separated by a comma to be used when bcc_on_receipt_email is true.
from_email String · max 100 Used for when you want to specify a different from email than your store's email address or when your store_email has a list of email addresses.
bcc_on_receipt_email Boolean Set this to true if you would like each receipt sent to your customer to also be blind carbon copied to your store's email address.
use_email_dns Boolean Set this to true if you have set up your DNS settings to include an SPF record for FoxyCart. See the FoxyCart documentation for more details.
send_html_email Boolean Set this to true if you want to send text and HTML email receipts and false if you send text emails only. This setting only impacts the main transaction receipt emails for the store.
smtp_config String · max 1000 If you'd like to configure your own SMTP server for sending transaction receipt emails, you can do so here. The JSON supports the following fields: username, password, host, port, security. The security value can be blank, ssl, or tls.
postal_code String · Required · max 50 The postal code of your store. This will be used for calculating shipping costs if you sell shippable items.
region String · Required · max 100 The two character code for states in the United States. Other countries may call this a province. When a two character code isn't available, use the full region name. This will be used for calculating shipping costs if you sell shippable items.
2 characters if code exists, otherwise.
country String · Required Two character ISO 3166-1-alpha-2 code for the country your store is located in. This will be used for calculating shipping costs if you sell shippable items.
locale_code String The locale code for your Store's locale. This will be used to format strings for your store.
Default: en_US if not supplied
hide_currency_symbol Boolean Set to true to prevent the currency symbol from being displayed (example: a points based checkout system).
hide_decimal_characters Boolean Set to true to prevent the decimal characters from being displayed (example: a points based checkout system).
use_international_currency_symbol Boolean Set true to use the international currency symbol such as USD instead of the regional one like $.
language String The default language for your store's cart, checkout, and receipt strings.
Default: english if not supplied
logo_url String · max 200 A URL to your store's logo which may be used in your store's templates.
checkout_type String The preferred configuration of your customer checkout experience, such as defaulting to guest checkout or requiring account creation with each checkout.
Default: default_account
use_webhook Boolean Set this to true to POST encrypted XML of your order to the webhook URL of your choice.
webhook_url String · Required · max 300 This is the URL of the webhook endpoint for processing your store's webhook. See the FoxyCart documentation for more details.
Required if use_webhook is true.
webhook_key String · Required This is the key used to encrypt your webhook data. It is also used as the legacy API key and the HMAC cart encryption key. It can either be a single string key or a JSON object with the keys cart_signing, sso, api_legacy, and xml_datafeed.
Required if use_webhook or use_cart_validation is true. Each key cannot be more than 100 characters.
use_cart_validation Boolean Set to true to use HMAC cart validation for your store.
use_single_sign_on Boolean Set this to true to redirect to your server before checkout so you can use our single sign on feature and log in your users automatically to FoxyCart or if you want to validate items before checkout.
single_sign_on_url String · Required · max 300 This is your single sign on URL to redirect your users to prior to hitting the checkout page. See the FoxyCart documentation for more details.
Required if use_single_sign_on is true.
customer_password_hash_type String When saving a customer to FoxyCart, this is the password hashing method that will be used.
Default: phpass
customer_password_hash_config String · max 100 Configuration settings for the customer_password_hash_type in use. See the FoxyCart documentation for more details.
features_multiship Boolean Set to true to turn on FoxyCart's multiship functionality for shipping items to multiple locations in a single order. See the FoxyCart documentation for more details.
products_require_expires_property Boolean Set to true to require all front-end add-to-cart interactions have a valid expires property.
app_session_time Integer If your store sells products which collect personal or sensitive information as product attributes, you may want to consider lowering your cart session lifespan. You can leave it as 0 to keep the default which is currently 43200 seconds (12 hours). The maximum allowed time is currently 1209600 seconds (14 days).
Format: Time in seconds
shipping_address_type String Used for determining the type of the customer address used when calculating shipping costs.
Default: determine_by_company
require_signed_shipping_rates Boolean Shipping rate signing ensures that the rate the customer selects is carried through and not altered in any way. If you're intending to make use of javascript snippets on your store to alter the price or label of shipping rates or add custom rates dynamically, disable this setting as it will block those rates from being applied. The default is false.
timezone String The timezone of your store. This will impact how dates are shown to customers and within the FoxyCart admin.
Default: America/Los_Angeles
unified_order_entry_password String · max 100 Set a master password here if you would like to be able to check out as your customers without having to know their password.
custom_display_id_config Object Instead of displaying the Foxy Transaction ID, you can display your own custom display ID on your store's receipt and receipt emails. Required fields: enabled (boolean), start (string, starting value), length (string, minimum digit length), prefix (string), suffix (string). Optionally includes a transaction_journal_entries object with: enabled (boolean), transaction_separator (string, max 10 chars), and log_detail_request_types containing prefix strings for each of: transaction_authcapture, transaction_refund, transaction_capture, transaction_void.
affiliate_id Integer This can only be set during store creation. Contact us if you need this value changed later.
Can only be set on creation.
is_maintenance_mode Boolean This setting makes your checkout page completely non-functioning. Your customers will see the maintenance notification language string instead. The default is false.
is_active Boolean · Read-only If this store is in development or if it has an active FoxyCart subscription and can therefore use a live payment gateway to process live transactions.
first_payment_date String · Read-only The date of the first payment for this FoxyCart store subscription. This can be considered the go live date for this store.
features String · max 500 This JSON config determines which features are turned on for the store. Currently the following features are supported: allow_transaction_editing. Values for the fields are true or false.
date_created String · Read-only The date this resource was created.
billing Object (nullable) · Read-only Information about the store's billing plan with Foxy. Returns null if the store doesn't have an active Foxy subscription. When active, contains: plan (the billing plan name), past_due (boolean), frequency (billing frequency such as '1y'), and billing_subscription_id.
date_modified String · Read-only The date this resource was last modified.
Link Relations (49)
self This Store fx:process_subscription_webhook POST here to resend the daily subscription webhook notification for this store fx:transaction_folders Transaction Folders for This Store fx:activate_store_starter_monthly_url Add-to-cart URL for the Starter plan with monthly billing fx:activate_store_starter_yearly_url Add-to-cart URL for the Starter plan with yearly billing fx:activate_store_growth_monthly_url Add-to-cart URL for the Growth plan with monthly billing fx:activate_store_growth_yearly_url Add-to-cart URL for the Growth plan with yearly billing fx:activate_store_advanced_monthly_url Add-to-cart URL for the Advanced plan with monthly billing fx:activate_store_advanced_yearly_url Add-to-cart URL for the Advanced plan with yearly billing fx:changelogs Change logs for this Store. fx:store on admin_email_template·fx:store on api_home·fx:store on applied_coupon_code·fx:store on applied_tax·fx:store on billing_address·fx:store on cart·fx:store on cart_include_template·fx:store on cart_template·fx:store on checkout_template·fx:store on coupon·fx:store on coupon_code·fx:store on coupon_code_transaction·fx:store on coupon_detail·fx:store on coupon_item_category·fx:store on custom_field·fx:store on customer·fx:store on customer_address·fx:store on customer_email_template·fx:store on customer_portal_settings·fx:store on default_payment_method·fx:store on discount·fx:store on discount_detail·fx:store on downloadable·fx:store on downloadable_purchase·fx:store on email_template·fx:store on error_entry·fx:store on fraud_protection·fx:store on gift_card·fx:store on gift_card_code·fx:store on gift_card_code_log_detail·fx:store on gift_card_item_category·fx:store on hosted_payment_gateway·fx:store on integration·fx:store on item·fx:store on item_category·fx:store on item_option·fx:store on item_taxes·fx:store on language_override·fx:store on native_integration·fx:store on payment·fx:store on payment_gateway·fx:store on payment_method_expiring·fx:store on payment_method_set·fx:store on payment_method_set_fraud_protection·fx:store on payment_method_set_hosted_payment_gateway·fx:store on receipt_template·fx:store on shipment·fx:store on store_changelog·fx:store on store_shipping_method·fx:store on store_shipping_service·fx:store on store_transaction_folder·fx:store on subscription·fx:store on subscription_event·fx:store on subscription_mrr_snapshot·fx:store on subscription_settings·fx:store on subscription_upcoming_item·fx:store on tax·fx:store on tax_item_category·fx:store on template_config·fx:store on template_set·fx:store on transaction·fx:store on transaction_journal_entry·fx:store on transaction_log·fx:store on transaction_log_detail·fx:store on user_access·fx:store on user_invitation·fx:store on webhook Example Representation
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/123",
"title": "This Store"
},
"fx:store_version": {
"href": "https://api.foxycart.com/property_helpers/store_versions/999",
"title": "This Store's Version"
},
"fx:attributes": {
"href": "https://api.foxycart.com/stores/123/attributes",
"title": "Attributes for This Store"
},
"fx:users": {
"href": "https://api.foxycart.com/stores/123/users",
"title": "Users for This Store"
},
"fx:user_accesses": {
"href": "https://api.foxycart.com/stores/123/user_accesses",
"title": "User Access for This Store"
},
"fx:user_invitations": {
"href": "https://api.foxycart.com/stores/123/user_invitations",
"title": "User Invitations for This Store"
},
"fx:customers": {
"href": "https://api.foxycart.com/stores/123/customers",
"title": "Customers for This Store"
},
"fx:carts": {
"href": "https://api.foxycart.com/stores/123/carts",
"title": "Carts for This Store"
},
"fx:transactions": {
"href": "https://api.foxycart.com/stores/123/transactions",
"title": "Transactions for This Store"
},
"fx:subscriptions": {
"href": "https://api.foxycart.com/stores/123/subscriptions",
"title": "Subscriptions for This Store"
},
"fx:subscription_events": {
"href": "https://api.foxycart.com/stores/123/subscription_events",
"title": "Subscription Events for This Store"
},
"fx:subscription_mrr_snapshots": {
"href": "https://api.foxycart.com/stores/123/subscription_mrr_snapshots",
"title": "MRR Snapshots for This Store"
},
"fx:subscription_upcoming_items": {
"href": "https://api.foxycart.com/stores/123/subscription_upcoming_items",
"title": "Upcoming Subscription Items for This Store"
},
"fx:subscription_settings": {
"href": "https://api.foxycart.com/store_subscription_settings/123",
"title": "Subscription Settings for This Store"
},
"fx:customer_portal_settings": {
"href": "https://api.foxycart.com/stores/123/customer_portal_settings",
"title": "Customer Portal Settings for This Store"
},
"fx:process_subscription_webhook": {
"href": "https://api.foxycart.com/stores/123/process_subscription_webhook",
"title": "POST here to resend the daily subscription webhook notification for this store"
},
"fx:item_categories": {
"href": "https://api.foxycart.com/stores/123/item_categories",
"title": "Item Categories for This Store"
},
"fx:taxes": {
"href": "https://api.foxycart.com/stores/123/taxes",
"title": "Taxes for This Store"
},
"fx:payment_method_sets": {
"href": "https://api.foxycart.com/stores/123/payment_method_sets",
"title": "Payment Method Sets for This Store"
},
"fx:coupons": {
"href": "https://api.foxycart.com/stores/123/coupons",
"title": "Coupons for This Store"
},
"fx:template_sets": {
"href": "https://api.foxycart.com/stores/123/template_sets",
"title": "Template Sets for This Store"
},
"fx:cart_templates": {
"href": "https://api.foxycart.com/stores/123/cart_templates",
"title": "Cart Templates for This Store"
},
"fx:cart_include_templates": {
"href": "https://api.foxycart.com/stores/123/cart_include_templates",
"title": "Cart Include Templates for This Store"
},
"fx:checkout_templates": {
"href": "https://api.foxycart.com/stores/123/checkout_templates",
"title": "Checkout Templates for This Store"
},
"fx:receipt_templates": {
"href": "https://api.foxycart.com/stores/123/receipt_templates",
"title": "Receipt Templates for This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/123/email_templates",
"title": "Email Templates for This Store"
},
"fx:error_entries": {
"href": "https://api.foxycart.com/stores/123/error_entries",
"title": "Error Entries for This Store"
},
"fx:downloadables": {
"href": "https://api.foxycart.com/stores/123/downloadables",
"title": "Downloadables for This Store"
},
"fx:hosted_payment_gateways": {
"href": "https://api.foxycart.com/stores/123/hosted_payment_gateways",
"title": "Hosted Payment Gateways for This Store"
},
"fx:fraud_protections": {
"href": "https://api.foxycart.com/stores/123/fraud_protections",
"title": "Fraud Protections for This Store"
},
"fx:transaction_folders": {
"href": "https://api.foxycart.com/stores/123/store_transaction_folders",
"title": "Transaction Folders for This Store"
},
"fx:gift_cards": {
"href": "https://api.foxycart.com/stores/123/gift_cards",
"title": "Gift Cards for This Store"
},
"fx:reports": {
"href": "https://api.foxycart.com/stores/123/reports",
"title": "Reports for This Store"
},
"fx:store_shipping_methods": {
"href": "https://api.foxycart.com/stores/123/store_shipping_methods",
"title": "Shipping Methods for This Store"
},
"fx:webhooks": {
"href": "https://api.foxycart.com/stores/123/webhooks",
"title": "Webhooks for This Store"
},
"fx:activate_store_starter_monthly_url": {
"href": "https://api.foxycart.com/activate_store_starter_monthly_url",
"title": "Add-to-cart URL for the Starter plan with monthly billing"
},
"fx:activate_store_starter_yearly_url": {
"href": "https://api.foxycart.com/activate_store_starter_yearly_url",
"title": "Add-to-cart URL for the Starter plan with yearly billing"
},
"fx:activate_store_growth_monthly_url": {
"href": "https://api.foxycart.com/activate_store_growth_monthly_url",
"title": "Add-to-cart URL for the Growth plan with monthly billing"
},
"fx:activate_store_growth_yearly_url": {
"href": "https://api.foxycart.com/activate_store_growth_yearly_url",
"title": "Add-to-cart URL for the Growth plan with yearly billing"
},
"fx:activate_store_advanced_monthly_url": {
"href": "https://api.foxycart.com/activate_store_advanced_monthly_url",
"title": "Add-to-cart URL for the Advanced plan with monthly billing"
},
"fx:activate_store_advanced_yearly_url": {
"href": "https://api.foxycart.com/activate_store_advanced_yearly_url",
"title": "Add-to-cart URL for the Advanced plan with yearly billing"
},
"fx:template_configs": {
"href": "https://api.foxycart.com/stores/123/template_configs",
"title": "Template Configs for This Store"
},
"fx:payment_gateways": {
"href": "https://api.foxycart.com/stores/123/payment_gateways",
"title": "Payment Gateways for This Store"
},
"fx:payment_methods_expiring": {
"href": "https://api.foxycart.com/stores/123/payment_methods_expiring",
"title": "Customer payment methods which are about to expire"
},
"fx:integrations": {
"href": "https://api.foxycart.com/stores/123/integrations",
"title": "Third party integrations which have been granted OAuth access to this store"
},
"fx:native_integrations": {
"href": "https://api.foxycart.com/stores/123/native_integrations",
"title": "Third party integrations which require credentials and configuration."
},
"fx:send_webhooks": {
"href": "https://api.foxycart.com/stores/123/send_webhooks",
"title": "Refeed webhooks v2 for this Store"
},
"fx:changelogs": {
"href": "https://api.foxycart.com/stores/123/changelogs",
"title": "Change logs for this Store."
},
"fx:transaction_journal_entries": {
"href": "https://api.foxycart.com/stores/123/transaction_journal_entries",
"title": "Transaction journal entries for This Store"
}
},
"store_version_uri": "https://api.foxycart.com/property_helpers/store_versions/20",
"store_name": "Example Store",
"store_domain": "example",
"use_remote_domain": false,
"store_url": "https://example.com/catalog",
"receipt_continue_url": "http://www.example.com/thankyou",
"store_email": "someone@example.com",
"from_email": "helpdesk@example.com",
"bcc_on_receipt_email": false,
"smtp_config": "{\"username\":\"someone@gmail.com\",\"password\":\"mycomplexpassword\",\"host\":\"smtp.gmail.com\",\"port\":\"465\",\"security\":\"ssl\"}",
"use_email_dns": false,
"postal_code": "37211",
"region": "TN",
"country": "US",
"locale_code": "en_US",
"hide_currency_symbol": false,
"hide_decimal_characters": false,
"use_international_currency_symbol": false,
"language": "english",
"logo_url": "",
"checkout_type": "default_account",
"use_webhook": true,
"webhook_url": "http://example.com/my_webhook_script",
"webhook_key": "some super secure password your mom could not not guess",
"use_cart_validation": false,
"use_single_sign_on": false,
"single_sign_on_url": "http://example.com/my_single_sign_on_script",
"customer_password_hash_type": "phpass",
"customer_password_hash_config": "8",
"features_multiship": false,
"products_require_expires_property": false,
"app_session_time": 43200,
"shipping_address_type": "residential",
"require_signed_shipping_rates": false,
"timezone": "America/Chicago",
"unified_order_entry_password": "here I am, buying all your stufz",
"custom_display_id_config": "{\"enabled\":true,\"start\":\"1\",\"length\":\"\",\"prefix\":\"TI-\",\"suffix\":\"\",\"transaction_journal_entries\":{\"transaction_separator\":\"-\",\"enabled\":true,\"log_detail_request_types\":{\"transaction_authcapture\":{\"prefix\":\"AC-\"},\"transaction_refund\":{\"prefix\":\"RF-\"},\"transaction_capture\":{\"prefix\":\"CP-\"},\"transaction_void\":{\"prefix\":\"VO-\"}}}}",
"affiliate_id": 0,
"is_maintenance_mode": false,
"is_active": false,
"first_payment_date": null,
"features": "{\"allow_transaction_editing\":true}",
"date_created": "2010-04-24T19:25:02-0700",
"date_modified": "2013-07-19T11:47:26-0700"
}