More documentation, examples

Hi! We're very interested in using FoxyCart for subscriptions on our site. We currently use Amazon simplepay, which is coming to end of life soon. I'm having a little difficulty figuring out what I need to do. I like what documentation there is, but I would like to see a few additions. Let me know if I should put this under "General Reqests" please.

First of all, there is a lot of repetition of "FoxyCart is different," followed by description of what it isn't and what features it boasts. But there isn't much explicit description of exactly what it is beyond the features/advantages. I think it would be very helpful (at least for me) to have an overview of not only why it's good or what it's good for, but what it does. I want to see how it is meant to work, flow of data/information, what happens in the browser when items are added to the cart and during checkout. I'd like a clear description of the sequence of events and communication between my servers, the user's browser, the foxycart servers, the payment gateway, etc. Some diagrams might be particularly useful for this, and it would be helpful to discuss/highlight differences in this regard between different gateways, how subscription payments and subscription updates work, and how they differ from products.

I'd also like to see complete examples. The explanations of the product parameters are good overall, but it would help to see them put together, how the parameters could be combined for various use cases.

The subscription parameters aren't as well documented. For example, there is not much explanation of sub_token and I haven't found an example on the wiki. The documentation says it's a url, but it isn't clear whether that's supposed to be the url on my site or on my foxycart subdomain, or what's supposed to happen when the url is accessed. Also the docs state that sub_token is "[v]ery useful when used in conjunction with the redirect feature as you can load up a customer's subscription and then redirect them back to your product page so they can add something to it." I am having some trouble grasping what exactly is meant by this. It's good to know *why* I might want to do this, but the docs don't state clearly *how* to use these together or *what* actually happens when I do. Perhaps a data flow diagram as I suggested above would help. Also I found very little description elsewhere of the redirect feature. It doesn't seem to be in the list of documented parameters. Should it be?

Another topic that isn't covered as fully in the documentation as I'd like is customers and authentication. The SSO documentation seems to indicate that customer sign-on is required for subscriptions, but there's no mention of this at all in the subscriptions documentation (SSO isn't even in the list of 'related documentation' links). Another thing that isn't stated clearly is whether customers' foxycart credentials are specific to my foxycart subdomain or work for all foxycart subdomains. When we process a subscription with amazon, the user has to sign in to amazon, but most users probably have amazon accounts already and the credentials are the same. If we send a user to foxycart, s/he is less likely to have foxycart credentials and (without SSO) might have to create a foxycart account as well. But if the foxycart account is specific to my foxycart subdomain, then the user is guaranteed not to have a foxycart account, so SSO integration essentially becomes a requirement for processing subscriptions.

Thanks for reading. Looking forward to more explanation/documentation.
A.L.
Comments
  • fc_adamfc_adam FoxyCart Team
    @altaurog,

    All great questions. We definitely hear you on the documentation too - there is a lot of information in there, but there are definitely some holes, and also it's not always easy to find the specific information you need. We are planning a rewrite of our documentation to hopefully address that.
    I want to see how it is meant to work, flow of data/information, what happens in the browser when items are added to the cart and during checkout.
    Probably the best way to experience that is to try out some of the example add to carts on our website here: http://www.foxycart.com/features/examples - that way you can see what the forms look like, and also what it looks like to add that to the cart and proceed through the checkout process.
    I'd also like to see complete examples. The explanations of the product parameters are good overall, but it would help to see them put together, how the parameters could be combined for various use cases.
    That's a great point - and while not extensive, the link above does have some examples of working add to carts.
    The subscription parameters aren't as well documented. For example, there is not much explanation of sub_token and I haven't found an example on the wiki.
    You'll find the majority of the discussion of subscriptions and sub_tokens on the subscriptions page here: http://wiki.foxycart.com/static/redirect/subscriptions

    The sub_token itself is essentially an identifier for a given subscription. So when a customer purchases a subscription for your store, that subscription will receive a unique sub_token value, much like a transaction has a transaction ID value.

    The sub_token can be used a few different ways - but it's purpose is always the same, as a way to access that particular subscription. So for example, when using our API - you would use the sub_token to fetch the information about that subscription.

    When used as part of your FoxyCart's store URL - then that relates to loading the subscription into the customers cart session so they can make some form of changes to the subscription. So when you load a URL like https://mystore.foxycart.com/cart?sub_token=ab123cde4fg567 in your browser - that will replace the customers cart with the contents of that particular subscription.

    If you haven't already - take a look over this section of the subscriptions wiki page - as I believe it should flesh out the additional details about the sub_token you're looking for: https://wiki.foxycart.com/v/2.0/products/subscriptions#the_sub_tokenwhat_it_is_and_how_to_use_it
    Also I found very little description elsewhere of the redirect feature. It doesn't seem to be in the list of documented parameters. Should it be?
    There isn't a heap of documentation surrounding that parameter - but you can see information about it on this page: https://wiki.foxycart.com/v/2.0/cheat_sheet
    The SSO documentation seems to indicate that customer sign-on is required for subscriptions, but there's no mention of this at all in the subscriptions documentation
    SSO isn't required at all for subscriptions to work. Utilising Single Sign On is completely optional, and only necessary if you're wanting to share logins between your website and FoxyCart so the customer doesn't need to log in twice.
    Another thing that isn't stated clearly is whether customers' foxycart credentials are specific to my foxycart subdomain or work for all foxycart subdomains.
    Customer logins are tied to a single FoxyCart store.
    When we process a subscription with amazon, the user has to sign in to amazon, but most users probably have amazon accounts already and the credentials are the same. If we send a user to foxycart, s/he is less likely to have foxycart credentials and (without SSO) might have to create a foxycart account as well.
    When utilising Amazon Payments (which I'm assuming is what you'll be using for your store?), the customer doesn't need a FoxyCart login at all. Once they reach the checkout they'll be able to click a button to login with their Amazon account, which will alter the checkout to show their Amazon information like addresses and payment information.

    I hope that answers your questions - if that raises any other queries or if I missed anything, let us know!
  • Adam,

    Thanks for the pointers. The examples page is helpful. I must have missed the more in depth discussion on sub_token the first time around, but I think what's missing from the documentation is a clear statement that the sub_token is generated by foxycart, not the merchant site.

    My only point about SSO is that having to create a new account both on my site and on my foxycart subdomain is a really terrible user experience. We wouldn't want to burden the user with any additional steps in completing payment. So even if technically SSO isn't required for subscription integration, since subscriptions require a foxycart sign-in, SSO is effectively required for practical purposes.

    Best,
    A.L.
  • fc_adamfc_adam FoxyCart Team
    @altaurog,

    If you're also allowing customers to login on your own site, then you're right - setting up SSO would definitely be an important step.
Sign In or Register to comment.