Purpose
External checkout integration allows you to host your main website separately to DecoNetwork and only link to your DecoNetwork site to allow the customer to customize and purchase your DecoNetwork products. The cart and checkout process is managed on your external site. This allows your existing e-commerce site to integrate with DecoNetwork, where the one order will have a mix of DecoNetwork products and products you already sell on your site.
Prerequisites
- You must be on the Enterprise plan to use this feature
- Programming experience is required to integrate with DecoNetwork using External Checkout Integration. All integration is done using browser links and direct server-to-server communication across HTTPS.
- All payments will be marked as “External API Payment” which acts like a manual payment. It is your responsibility to make sure this payment is valid.
- The External Cart API app must be enabled (Go to Admin > Apps Store in the Fulfillment Center to enable the app).
To enable the External Checking Integration API app in DecoNetwork
- Log into your DecoNetwork website.
- Browse to Admin and select the yellow + Apps Store button at the bottom of the Main Menu.
- Scroll to the Website Tools section.
- Click Add now on the External Cart API app.
Overview
Actors:
- External Website: Your existing website that sells products and has a cart/checkout process.
- DecoNetwork Website: Your DecoNetwork website that allows customers to customize blank products, sell decorated products, and sell designs on products.
- Customer: Your customer who will be following links between the external website and the DecoNetwork website using their browser.
Workflow:
- Your customer will be browsing your external website, and viewing products. The products will be a mix of non-decoratable products that you are selling already and DecoNetwork products. Adding the DecoNetwork products to the external website is outside the scope of this document, and depends on the implementation of the external website.
- The customer clicks on a DecoNetwork product.
- The customer is directed to the DecoNetwork website, specifying the product/size and color.
- The customer decorates the specified product and clicks “Add to cart”.
- The customer is redirected back to the external website with details about the product just added.
- The external website will parse the parameters and add an entry to the cart to represent the line item just added through DecoNetwork. The parameters contain a unique ID, thumbnail URL, edit URL, and other description/pricing fields that can be used to display the line item in the external cart.
- The customer continues browsing on the external website.
- The customer checks out on the external website and pays for the order.
- Money is taken through the external website.
- The external website then makes a direct call using HTTPS to the DecoNetwork website to “commit” the order lines that have been just purchased. This call is server to server.
- An order will be added to your Business Hub containing the line items committed after checkout has been completed via your external cart.
A note on external cart tracking:
If an external cart/order ID (generated at your end) is passed through whenever a call is made to the DecoNetwork API, the order held at DecoNetwork's end will persist across multiple sessions, even if the individual order line items have not been committed.
If no external cart/order ID is passed through to DecoNetwork, the default behavior is assumed, and line items cannot be edited in a different session (for example, if a user closes their browser).
Linking to DecoNetwork to load a product
At some point on your website, the customer will click a link that will take them to your DecoNetwork website to allow the customer to purchase a product defined in DecoNetwork. This is step 3 in the above workflow.
URL:
https://<deconetwork_store_secure_url>/external/load_resource?<parameters>
Parameters:
| Name | Description |
|---|---|
| mode |
designer: load a blank product into the designer. designer_predec: load a decorated product into the designer. blank: load a blank product into the product details page. predec: load a decorated product into the product details page. view_design: load a design into the design details page. design: load the design on the product page with the specified design and blank product. |
| product | The ID of the blank product, or when the mode is “predec/designer_predec”, the ID of the decorated product. Not used when mode is “view_design”. |
| size | The id of the size |
| quantity | The quantity to populate into the specified size |
| color_id | The id of the color. |
| design | The id of the design (only applicable when the mode is “design” or “view_design”) |
| callback_add_url | The URL to redirect the customer back to when they click add to cart |
| callback_cancel_url | The URL to redirect the customer back to when they click the “close” button on the popup designer |
| calback_param_XXXX | You can add call-back parameters which will be added when the customer id redirected back to the external website after adding the item to the cart. Note: only the part after “callback_param_” is sent back. E.g.: if callback_param_XXXX=123 was passed, then XXXX=123 would be a parameter sent to the callback_add_url. |
| oid | External cart or order ID. This should be unique for each order. |
| cart_hold | The number of days an open (unfinished) order will be kept on DecoNetwork's end from the date the order is created (default 30 days, maximum 60). An order is created when a user clicks “Add to cart”. |
| iframe_mode | If you are embedding your DecoNetwork site in an iframe, set the iframe_mode parameter to 1 so the DecoNetwork 'session identifier' will be passed in the request URL instead of a cookie because some browsers will not pass cookies to iframes on a different domain. |
Processing "Add to cart" callback:
After the customer has added an item to their cart, they will be redirected back to the external website with a list of parameters describing the product just added to the cart. The external website will then add an item to their cart to represent this DecoNetwork product. Because of the amount of metadata against a DecoNetwork product, the full definition of the line item remains in DecoNetwork, with enough information to link and display the line item sent back to the external website. This is step 6 in the above workflow.
The URL the customer is redirected back to will either be the “callback_add_url” passed during the initial link or the “Add To Cart callback url” specified against the website in the Store Settings.
Parameters:
| Name | Description |
|---|---|
| id | The unique id of the line item in DecoNetwork. This is used to commit the order. |
| name | The name of the product ordered. |
| tn | A URL to a thumbnail relative to the DecoNetwork website. |
| options | An HTML string of the options chosen (including size) |
| qty | The line item qty specified on the item |
| discount | The discount amount applied to the item |
| tax | Tax amount applied to the item |
| line_total | The total amount of the line item |
| edit_link | If you want the customer to be able to edit the item, you can direct them this URL. The URL is relative to the DecoNetwork website. When the customer edits a line item and clicks the update button they will be redirected back to the same callback URL with the same unique ID, but with details updated. |
| ec | A list of extra charges associated with the line item. Note the extra charge information will be passed back with each line item even if it's a reused charge. On DecoNetwork, extra charges are only applied once per order; your cart will need to use similar logic to only add an extra charge if it's not already in the cart. Includes the following parameters: ID, name, total |
Committing DecoNetwork order lines:
The external website needs to notify the DecoNetwork website when the checkout process is completed to let DecoNetwork know that the items have actually been ordered. This will make the order appear on the DecoNetwork Business Hub and Production Screens.
URL:
https://<deconetwork_secure_url>/external/commit_order?<parameters>
Parameters:
| Name | Description |
|---|---|
| ids | A list of comma-separated line item IDs returned from the “add to cart” call-back. |
| auth | The “Commit Order Password” from the store settings. This is to ensure that only authorized entities can commit an order. |
| user_id | Optional parameter; can be included to assign the order to an existing customer. User IDs are passed back as a response to the commit order request and can be stored on the external cart for future reference. |
| shipping_method_id | The id of the shipping method. If not passed, the “Default Shipping Method” from the store settings is used. |
| mark_as_paid | {true|false} If true, then the order will be marked as paid. If not true, then the manual payment method will need to be confirmed before it goes into production. |
| invoice_id | Override the invoice ID of the order. MUST BE UNIQUE. If not used, the default DecoNetwork invoice ID is used. |
| oid | External cart or order ID. This should be the same ID that was sent during the load_resource request. If any line items have a different external order ID, the entire commit will fail. |
| billing_email | Customer billing details |
| billing_country_code | Customer billing details - 2 letter country code (UPPERCASE) |
| billing_firstname | Customer billing details |
| billing_lastname | Customer billing details |
| billing_zip | Customer billing details |
| billing_company | Customer billing details |
| billing_salutation | Customer billing details |
| billing_ph_number | Customer billing details |
| billing_street | Customer billing details |
| billing_city | Customer billing details |
| billing_state | Customer billing details |
| separate_shipping_details | Provide separate customer shipping details? {true|false} |
| shipping_country_code | Customer shipping details - 2 letter country code (UPPERCASE) |
| shipping_firstname | Customer shipping details |
| shipping_lastname | Customer shipping details |
| shipping_zip | Customer shipping details |
| shipping_company | Customer shipping details |
| shipping_salutation | Customer shipping details |
| shipping_ph_number | Customer shipping details |
| shipping_street | Customer shipping details |
| shipping_city | Customer shipping details |
| shipping_state | Customer shipping details |
Commit Response:
If the commit succeeds, the HTTP code will be 200 with 3 lines of text:
OK
INVOICE_ID
USER_ID
If the commit fails, the HTTP code will be 500 with 2 lines of text:
ERROR <NUMBER>
ERROR_DESCRIPTION
PHP Sample Code:
An example implementation in PHP is available. Download now.
Removing a DecoNetwork order line:
The external website needs to notify the DecoNetwork website when a line item that has extra charges is removed from the external cart.
URL:
https://<deconetwork_secure_url>/external/remove_item?<parameters>
Parameters:
| Name | Description |
|---|---|
| id | The line item ID returned from the “add to cart” call-back. |
| auth | The “Commit Order Password” from the store settings. This is to ensure that only authorized entities can remove an item. |
| oid | External cart or order ID. This should be the same ID that was sent during the load_resource request. |
Remove Item Response:
If the remove succeeds, the HTTP code will be 200 with 2 lines of text:
OK
INVOICE_ID
If the remove fails, the HTTP code will be 500 with 2 lines of text:
ERROR <NUMBER>
ERROR_DESCRIPTION
Comments
5 comments
4. Click Add now on the External Cart API app.
This does not exist under the website tools.
Under the website tools only these below available (any help? how to enable
External Shopping Cart Integration)
Hi Phil, APIs are available on the Enterprise plan only, whereas you are on the Premium.
That sucks as deconetwork cart is really poorly made, it is 2020 and deco still does not accept Apple Pay/Amazon Pay.
I am using deco network over 3 years as of now (before was using inksoft) over the 3 years deco did not make any solid improvements, good features or required updates but joke features and updates and just for a API you want us to pay $400 a month and $4K licensee fee is a joke tbh.
In the forums top 100 ideas waiting more than 6 years and some shows "accepted" and still no updates on those ideas.
I am really considering leaving deco network as it is clear that deco network trying to get as much money possible from us and do not make any solid improvements. I also want to tell that for new customers you do discounts/deals/coupons but for a old users like us for an upgrade there is no deal at all. ( We were in business+ plan last year and had to pay full license fee to upgrade to Premium while a new customer paid $300 to $500 less than us)
Truly disappointed
Best
Phil
Appreciate the feedback Phil. This external cart integration wouldn't resolve your concerns with the checkout process as it would create a whole separate burden for you of creating your DecoNetwork products in an external ecommerce platform. The purpose of this integration provide a way to those already selling on an external ecommerce system to offer customized goods through the DecoNetwork designer.
We're always making improvements to the system and certainly the ideas page is one place for you to share feedback on what areas of the system you would like to see improved. As we continue to implement ideas many of them off the top 100 requested list, newer ideas are flowing into the list for consideration.
Is there a video explaining the procedure of integrating and ways to check the integration done properly. For an affiliate store, if they activate external cart and integrate their external cart, how the commission gets calculated? does the commission gets allocated as it should be?
Thanks
Swetang
Please sign in to leave a comment.