API – External Checkout Integration
Purpose
External checkout integration allows you to host your main website separately to DecoNetwork and only link to your Altacolor DecoNetwork site to allow the customer to customize and purchase your Altacolor 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 Altacolor 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 Altacolor 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 Altacolor affiliate 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.
- Altacolor DecoNetwork Website: Your Altacolor 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 Altacolor 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 Altacolor DecoNetwork products. Adding the Altacolor 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 Altacolor DecoNetwork product.
- The customer is directed to the Altacolor 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 Altacolor 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 Altacolor 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 Altacolor DecoNetwork API, the order held at Altacolor 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 Altacolor 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 Altacolor DecoNetwork to load a product
At some point on your website, the customer will click a link that will take them to your Altacolor DecoNetwork website to allow the customer to purchase a product defined in Altacolor DecoNetwork. This is step 3 in the above workflow.
URL:
https://<altacolor_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 Altacolor 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 Altacolor DecoNetwork site in an iframe, set the iframe_mode parameter to 1 so the Altacolor 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 Altacolor DecoNetwork product. Because of the amount of metadata against a Altacolor DecoNetwork product, the full definition of the line item remains in Altacolor 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 Altacolor DecoNetwork. This is used to commit the order. |
| name | The name of the product ordered. |
| tn | A URL to a thumbnail relative to the Altacolor 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 Altacolor 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 Altacolor 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 Altacolor DecoNetwork order lines:
The external website needs to notify the Altacolor DecoNetwork website when the checkout process is completed to let Altacolor DecoNetwork know that the items have actually been ordered. This will make the order appear on the Altacolor DecoNetwork Business Hub and Production Screens.
URL:
https://<altacolor_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 Altacolor 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 Altacolor DecoNetwork order line:
The external website needs to notify the Altacolor DecoNetwork website when a line item that has extra charges is removed from the external cart.
URL:
https://<altacolor_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
IMPORTANT NOTICE: The following notice pertains to Altacolor LLC’s responsibilities and the user’s rights as regards API use and may affect a user’s legal rights. Read carefully, as use of any product or technological facility provided by Altacolor LLC binds the user to these terms:
- Altacolor LLC is a limited-liability company formed in the United States, with a nexus in the state of Texas.
- Altacolor LLC does not provide support for API functions and does not guarantee or warrant performance, correctness, or fitness for a specific purpose of this software. Use of these API functions are SOLELY at the risk of the user. Use of the provided API is acknowledgement by the user of the foregoing and the user assumes all risk, loss or any other consequence of using these functions in whole or in part and further specifically indemnifies Altacolor LLC, its principals, employees, subsidiaries, affiliates, assigns, agents or representatives from any harm that may arise for the use of or access to the supplied API(s).
- Altacolor LLC makes no representations regarding the security or lack thereof of data in whole or part shared using the API or as stored on Altacolor LLC’s servers whether onsite or remotely. The user shall at all times maintain appropriate data security and breach insurance that indemnifies Altacolor LLC, its principals, employees, subsidiaries, affiliates, assigns, agents or representatives against loss whether material or otherwise and further includes any axillary fees and costs such as legal fees, consulting fees, government fees, technology fees or any other sundry costs and fees that may be associated with legal action any action contemplated by the user or a third party actor.
- If any provision set forth herein is held to be illegal, invalid, or unenforceable under present or future laws effective during the term of this agreement, such provision is fully severable, and this agreement must be construed and enforced as if such illegal, invalid, or unenforceable provision never comprised a part of this agreement; and the remaining provisions of this agreement remain in full force and effect and may not be affected by the illegal, invalid, or unenforceable provision or its severance from this agreement.
