| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:2.0:using_foxy_without_the_cart [2017/05/29 03:26] – foxybrett | v:2.0:using_foxy_without_the_cart [2018/02/13 07:15] (current) – [Taxes] adam |
|---|
| A normal Foxy integration would look like this: | A normal Foxy integration would look like this: |
| |
| - Your website has "add to cart" or "buy now" (or "donate now", etc.) buttons (links or forms). These buttons are ''a'' or ''form'' pointing to the ''/cart'' endpoint of your FoxyCart account. | - Your website has "add to cart" or "buy now" (or "donate now", etc.) buttons (links or forms). These buttons are ''a'' or ''form'' elements pointing to the ''/cart'' endpoint of your FoxyCart account. |
| - A customer clicks one of those buttons. The browser submits a ''GET'' or ''POST'' request to the Foxy ''/cart'' endpoint. The cart is then displayed. By default, this would be the "sidecart" that slides in from the right, but it could also direct the customer to a new webpage showing only the cart, or it could take the customer directly to the checkout (which displays the cart in the right column). | - A customer clicks one of those buttons. The browser submits a ''GET'' or ''POST'' request to the Foxy ''/cart'' endpoint. The cart is then displayed. By default, this would be the "sidecart" that slides in from the right, but it could also direct the customer to a new webpage showing only the cart, or it could take the customer directly to the checkout (which displays the cart in the right column). |
| - The customer lands on the Foxy-hosted checkout page. The customer completes the page and clicks to submit their payment. | - The customer lands on the Foxy-hosted checkout page. The customer completes the page and clicks to submit their payment. |
| Let's imagine that you've already got your own cart functionality, however, and your "add to cart" buttons are already pointing to your own system. You want to continue using that functionality, but to have Foxy take over at the checkout portion. Here's how your integration would differ from the approach above: | Let's imagine that you've already got your own cart functionality, however, and your "add to cart" buttons are already pointing to your own system. You want to continue using that functionality, but to have Foxy take over at the checkout portion. Here's how your integration would differ from the approach above: |
| |
| - Your website's "add to cart" buttons point to your ownsystem, and not to your store's ''/cart'' endpoint. | - Your website's "add to cart" buttons point to your own system, and not to your store's ''/cart'' endpoint. |
| - Any cart that is displayed (prior to the checkout) is entirely handled by your system. | - Any cart that is displayed (prior to the checkout) is entirely handled by your system. |
| - When the customer indicates they'd like to pay, your system… | - When the customer indicates they'd like to pay, your system… |
| curl https://YOURDOMAIN.foxycart.com/cart\?name\=Cool%20Example\&price\=10\&color\=red\&code\=sku123\&output\=json | curl https://YOURDOMAIN.foxycart.com/cart\?name\=Cool%20Example\&price\=10\&color\=red\&code\=sku123\&output\=json |
| </code> | </code> |
| | |
| | (Alternately, you could do a ''POST'' to your ''/cart'' endpoint, which may be easier if you're doing serverside interactions.) |
| |
| You'll see JSON like this: | You'll see JSON like this: |
| |
| === The Hypermedia API === | === The Hypermedia API === |
| | |
| | <WRAP important> |
| | //**__Experimental Functionality__**// |
| | Though creating a cart via the hypermedia API is supported (and being used in production by some of our users), please drop us a note if you proceed with this approach, and if you encounter anything unexpected. Retrieving and setting shipping rates, in particular, isn't currently supported by the hypermedia API, so you'll need to use non-hAPI approaches (described below) in certain situations. |
| | </WRAP> |
| |
| If you're building a deeper integration, you may already be working with our [[https://api.foxycart.com/|Hypermedia REST API]]. For the purposes of this page, we'll assume basic working knowledge of the hAPI (including authentication via OAuth 2.0 and how to navigate using the hypermedia link relationships). This hAPI approach provides considerably more functionality, as well as a consistent interface for all things related to your Foxy account, and can replicate the above ''/cart'' endpoint approach, albeit with a few more steps. | If you're building a deeper integration, you may already be working with our [[https://api.foxycart.com/|Hypermedia REST API]]. For the purposes of this page, we'll assume basic working knowledge of the hAPI (including authentication via OAuth 2.0 and how to navigate using the hypermedia link relationships). This hAPI approach provides considerably more functionality, as well as a consistent interface for all things related to your Foxy account, and can replicate the above ''/cart'' endpoint approach, albeit with a few more steps. |
| There are some examples of code on [[.:sso#outgoing_ssologging_a_customer_into_your_own_site_from_foxycart|the receipt documentation]], and if you're doing incoming SSO, it will be very familiar to you at this point. | There are some examples of code on [[.:sso#outgoing_ssologging_a_customer_into_your_own_site_from_foxycart|the receipt documentation]], and if you're doing incoming SSO, it will be very familiar to you at this point. |
| |
| Note that though we don't support SAML by default, we can implement SAML for our Enterprise users. (Because of the complexities of synching users, it's not something that works "off the shelf", but it is doable either by use, or by you using an intermediary script to go from SAML to our own SSO approach.) | Note that though we don't support SAML by default, we can implement SAML for our Enterprise users. (Because of the complexities of synching users, it's not something that works "off the shelf", but it is doable either by us, or by you using an intermediary script to go from SAML to our own SSO approach.) |
| |
| |
| | |
| | ===== Shipping, Taxes, Coupons, and Other Considerations ===== |
| | For this section, we'll be using the ''/cart'' endpoint, not the hypermedia API. (This functionality will be added to the hAPI, but is currently unavailable there.) |
| | |
| | ==== Taxes ==== |
| | Taxes are applied automatically during the checkout process, but if you'd like to retrieve a tax estimate during your own checkout flow, you'd do the following: |
| | |
| | - Create the cart and session as outlined above. |
| | - Attach a postal code to the session. Do this via the browser and review the javascript requests and responses made for your particular account, but it'll look something like this: ''https://EXAMPLE.foxycart.com/v/2.0.0/api_json.php?city=San+Diego®ion=CA&postal_code=92106&country=US&ThisAction=SaveCartContactInfo&fcsid=XXX&store_id=XXX'' (where you'd replace the ''XXX'' and domain as appropriate). |
| | * There's also a ''GetAddressByPostalCode'' action that will retrieve possible cities based on an entered postal code, if you'd like to use that like the Foxy checkout, to do a bit of address validation. (This can help ensure more accurate tax rates.) |
| | - Retrieve the tax information with a request to ''https://EXAMPLE.foxycart.com/cart?fcsid=XXX&output=json''. Display it however you'd like. |
| | - **Note:** You may need to repeat the previous step after setting the shipping details for the transaction, as the tax value may change based on the shipping cost. |
| | |
| | ==== Shipping ==== |
| | Shipping is also handled on the checkout automatically, but there may be situations where you'd like to set the shipping details (method name and price) without user input. There are a few possibilities here. |
| | |
| | === Step 1: Adding the rate to the session === |
| | |
| | The basic idea involves a request like this: |
| | |
| | <code> |
| | https://EXAMPLE.foxycart.com/v/2.0.0/api_json.php?shipping_address_name=YYY&shipping_service_id=XXX&shipping_service_description=UPS+Ground&total_shipping=16.65&total_future_shipping=0&ThisAction=SaveShippingServiceInfo&fcsid=XXX&store_id=XXX |
| | </code> |
| | |
| | (Note that the ''YYY'' value is used for [[.:multiship|multiship addresses]], and will normally be left empty if you're not using multiple shipping addresses in a single transaction.) |
| | |
| | **Using Foxy's Built-In Shipping Functionality:** |
| | If you complete the steps above to get a tax, you'll notice the cart's JSON now contains a ''shipping_results'' node. You can use those values to submit back to the cart, passing through the values like the link above. Note that you can still use the [[.:shipping#custom_shipping_endpoint|custom shipping endpoint]] with this approach. |
| | |
| | **Using Arbitrary Shipping Amounts:** |
| | You can also pass through arbitrary shipping details, which may be preferable in certain situations. A few caveats: |
| | |
| | * The ''shipping_service_id'' should be an integer greater than 10000. |
| | * Signing requests: We are currently working to allow this approach to work with the "shipping rate signing" functionality enabled. Contact us for details. |
| | |
| | If you're going to use the Hypermedia API to push through the transaction programmatically at this point, you're done. If you're going to pass the customer on to the ''/checkout'' page to complete the transaction themselves, continue to Step 2. |
| | |
| | === Step 2: Handling the shipping on the checkout === |
| | |
| | This section will seem like extra work, and in many ways it is, but it ensures the integrity of the checkout. Even though you've already set the shipping rate you want, you'll need to do this again using the [[.:shipping#custom_shipping_endpoint|custom shipping endpoint]] functionality. |
| | |
| | If your endpoint returns the same details as you set in Step 1 above, the checkout will load with that shipping rate already selected and ready to go. |
| | |
| | (Note: If you're using [[.:sso|SSO (Single Sign On)]] and the user is authenticated, the rate may not be selected. Please contact us to discuss options with you so your users can avoid needing to select the shipping rate.) |
| | ==== Coupons ==== |
| | If you handle your own coupons or discounts within your system, you'll want to ensure those get passed through to Foxy appropriately. At present, Foxy doesn't allow passing through arbitrary discount/coupon amounts like it does shipping (above), so this is a bit more involved. |
| | |
| | - Calculate the appropriate discount in your system. Let's assume it's $10. |
| | - [[https://wiki.foxycart.com/v/2.0/shipping#custom_shipping_endpoint|Create a coupon code]] using the hAPI for that amount (with the appropriate other details like display name and such). |
| | - Add that coupon to the existing cart with a request like ''/cart?coupon=XXX'', where ''XXX'' is the coupon code as configured. |
| | |
| | A few notes: |
| | |
| | * You can remove coupons if necessary with a link like ''/cart?cart=remove_coupon&coupon_code_id=XXX&fcsid=XXX''. The respective ''coupon_code_id'' is available within the ''coupons'' node of the cart JSON for each coupon currently applied to the cart. |
| | * If you have discounting logic that fits with Foxy's functionality, we recommend piggybacking on that. For example, if you have quantity discounts, we'd recommend using Foxy's built-in logic rather than calculating a discount and creating a unique code per transaction. Similarly, if a coupon's discounting logic can be replicated in Foxy, you can create a single coupon and reuse it. |
| |
| ===== Putting It All Together ===== | ===== Putting It All Together ===== |
| |
| Please let us know if you have any questions about this approach. You can always reach out to our support email. For advanced integrations like this, however, we are only able to offer support to users on our API Premium or Single-Store Advanced plans. | Please let us know if you have any questions about this approach. You can always reach out to [[http://www.foxycart.com/contact|our support email]]. For advanced integrations like this, however, we are only able to offer support to users on our API Premium or Single-Store Advanced plans. |
| | |
