Got questions? Leave your message here or Schedule a quick call with our manager now

General Service Questions

Event takes place when a user or an owner interacts with the shopping cart for some purpose. For example, events may be considered as user registration, product adding/updating or some other changes on the store.

API2Cart cannot establish real-time synchronization with the store. However, it is feasible to sync with the store periodically (e.g. every 3 minutes) and retrieve all the necessary data in the shortest time possible.

We return Live Shipping Rates on Shopify, Magento, Magento 2, and WooCommerce for now (November 2021)

Methods:

/basket.live_shipping_service.list.json

/basket.live_shipping_service.create.json

/basket.live_shipping_service.delete.json

 

How it works?

Create new shipping service on the store

/basket.live_shipping_service.create.json

      On WooCommerce stores there can be an unlimited amount of services, but on Shopify you can create only one sevice (Shopify limit).

      To create the service you’ll have to specify the name of the service and callback url, that will return us shipping rates. We validate the callback when it is being created by sending test request to it. Test requests contain header X-Shipping-Service: 1.  

      To check it the request was really sent by API2Cart, compare header signature X-Shipping-Service-Signature

      The signature is built based on all headers that start with X-Shipping-Service, except for X-Shipping-Service-Signature.

 

Video tutorial:

 

The algorithm:

      1. Create array of headers, let the header name be its key, its value - the header value string.

      2. Sort the headers by the name.  

      3. Create the string for signature, that is made of headers. For that, encode the array of headers in JSON and concatenate from request body.

      4. Calculate sha256 signature in binary format

      5. Convert the binary signature to base64

 

Php example:

      $headersToSign = [

      'X-Shipping-Service-Test-Request' => '1',

      'X-Shipping-Service-Request-Timestamp' => '1553177278'

      ];

      ksort($headersToSign);

      $headersJson = json_encode($headers);

      $sign = base64_encode(hash_hmac('sha256', $headersJson . $body, $signingKey, true));

 

Test request example (from API2Cart)

 

REQUEST: POST /rates.php

Host: www.stores.local

Connection: close

User-Agent: Zend_Http_Client

accept-encoding: identity

content-type: application/json

accept: application/json

X-Shipping-Service-Signature: Q4jaFbiUKJW2gjTHqvlRrWMUOx65CaepT0BaKFiw6a0=

X-Shipping-Service-Test-Request: 1

X-Shipping-Service-Request-Timestamp: 1553609265

Content-Length: 1880

{

   "packages": [

       {

           "id": "1",

           "currency_code": "USD",

           "origin": {

               "first_name": null,

               "last_name": null,

               "postcode": "35004",

               "address1": "Test, 1\/1",

               "address2": "",

               "phone": "",

               "city": "Moody",

               "country": {

                   "code2": "US",

                   "code3": "USA",

                   "name": "United States of America"

               },

               "state": {

                   "code": "AL",

                   "name": "Alabama"

               },

               "company": null

           },

           "destination": {

               "first_name": null,

               "last_name": null,

               "postcode": "35005",

               "address1": "Test, 1\/1",

               "address2": "",

               "phone": "",

               "city": "Adamsville",

               "country": {

                   "code2": "US",

                   "code3": "USA",

                   "name": "United States of America"

               },

               "state": {

                   "code": "AL",

                   "name": "Alabama"

               },

               "company": null

           },

           "items": [

               {

                   "product_id": "1",

                   "model": "t1",

                   "name": "Test Product 1",

                   "price": 100.99,

                   "quantity": 5.5,

                   "discount_amount": null,

                   "total_price": 555.45,

                   "tax_percent": 21,

                   "tax_value": 116.64,

                   "variant_id": null,

                   "weight_unit": "kg",

                   "weight": 5.5

               }

           ]

       },

       {

           "id": "2",

           "currency_code": "USD",

           "origin": {

               "first_name": null,

               "last_name": null,

               "postcode": "35004",

               "address1": "Test, 1\/1",

               "address2": "",

               "phone": "",

               "city": "Moody",

               "country": {

                   "code2": "US",

                   "code3": "USA",

                   "name": "United States of America"

               },

               "state": {

                   "code": "AL",

                   "name": "Alabama"

               },

               "company": null

           },

           "destination": {

               "first_name": null,

               "last_name": null,

               "postcode": "35005",

               "address1": "Test address",

               "address2": "",

               "phone": "",

               "city": "Adamsville",

               "country": {

                   "code2": "US",

                   "code3": "USA",

                   "name": "United States of America"

               },

               "state": {

                   "code": "AL",

                   "name": "Alabama"

               },

               "company": null

           },

           "items": [

               {

                   "product_id": "1",

                   "model": "t1",

                   "name": "Test Product 1",

                   "price": 100.99,

                   "quantity": 5.5,

                   "discount_amount": null,

                   "total_price": 555.45,

                   "tax_percent": 21,

                   "tax_value": 116.64,

                   "variant_id": null,

                   "weight_unit": "kg",

                   "weight": 5.5

               },

               {

                   "product_id": "1",

                   "model": "t2",

                   "name": "Test product 2",

                   "price": 100.99,

                   "quantity": 5.5,

                   "discount_amount": null,

                   "total_price": 555.45,

                   "tax_percent": 21,

                   "tax_value": 116.64,

                   "variant_id": null,

                   "weight_unit": "kg",

                   "weight": 5.5,

                   "additional_fields": {

                       "dimensions_unit": "cm",

                       "height": 3.5,

                       "width": 2.15,

                       "length": 10.36

                   }

               }

           ]

       }

   ]

}

 

Once you get test request, your endpoint have to respond in JSON format

The response will differ for different shopping carts

For instance, from Shopify response structure will look like the following:

{  

  "packages_rates":[  

     {  

        "package_id":"1",

        "rates":[  

           {  

              "name":"Some name",

              "description":"Tax included an duties",

              "code":"some_name",

              "currency":"USD",

              "total_cost":10.56

           },

           {  

              "name":"Some name 2",

              "description":"Tax included an duties",

              "code":"some_name2",

              "currency":"USD",

              "total_cost":20.59,

              "min_delivery_timestamp":1558177278,

              "max_delivery_timestamp":1559177278

           }

        ]

     }

  ]

}

 

For WooCommerce the response structure will look like that:

{  

  "packages_rates":[  

     {  

        "package_id":"1",

        "rates":[  

           {

     "name": "Some name",

     "code": "some_name",

     "total_cost": 10.56,

"taxable" : true,

"tax_value": 2.12/*pass tax value*/

   },

   {

     "name": "Some name",

     "code": "some_name",

     "total_cost": 10.56,

"taxable" : false/*disable tax*/

   },

   {

     "name": "Some name",

     "code": "some_name",

     "total_cost": 10.56,

     "taxable" : true /*tax calculated using store tax rates*/

   },

...

        ]

     }

  ]

}

When we send a certain amount of packages, we expect to get the same amount of packages_rates objects. The property rates can be empty, which means there can be no rates for a certain package.

If the structure is not valid, we return an error. For example, you will get error when you pass a string in total_cost.

{

   "return_code": 109,

   "return_message": "Bad Response. Field \"rates->0->total_cost\" has wrong type. It must be decimal",

   "result": {}

}

If the callback returns 404 error code, we will not try again

If the callback returns 200 error code, we will check response validity and then return it to the store in the format that fits the store.

If the store returns 200 error code, butwith empty or incorrect response, we will wait 2 seconds and will try again.

If the callback don’t respond in 15 seconds, we will throw an error and will not try again.

{

   "return_code": 109,

   "return_message": "Callback https://www.stores.local/rates.php did not respond within 15 sec",

   "result": {}

}

If everything is ok, the new service will be created.

 

2) When the store requests rates, we unify the request and send it to callback specified when the service was created. Also, we send X-Shipping-Service-Id header.

 

If the response is not valid or the callback didn’t answer, we will log the error and increment error count of the shipping service by 1. If the next request will be successful, the count will be reduced to zero. Soon we will add the functionality that will turn off the service when the error limit is exceeded.

1. Open cPanel and find the FTP Accounts icon.

cPanel

2. Add an account to allow access to your server via FTP.

FTP Accounts

Fill in the following fields:

  • Login (it is the username for FTP access);
  • Password and Password (again) (you can use Password Generator create random passwords);

cPannel password generator

It is recommended to use strong passwords. The system will show you whether your password is strong enough.

  • Directory (it is a root directory for FTP access; it is recommended to change it for public_html);
  • Quota (it can be left without any modifications).

After you have filled in all the information necessary, you get something like this:

Add FTP Account

3. Click on Create FTP Account and have your account created.

FTP Account Created

Yes, API2Cart supports the following shopping carts plugins:

You can also download some plugins in the "Plugins" section of your API2Cart account.

The main difference between the Enterprise On-Premise solution and the other plans provided by API2Cart is that no one except your team will have access to the service resources (as it will be on your chosen server). Enterprise On-Premise solution guarantees you the highest level of data security that can be provided by API2Cart.

You can take sole control of who can manage your API2Cart server infrastructure by using the functionality provided by Amazon Web Service (AWS), Microsoft Azure, Hetzner Cloud, and Google Cloud Platform. Also, you can use API2Cart service on your own server.

All requests will be made over HTTPS protocol.

With the Enterprise On-Premise solution, you will be able to manipulate the data from as many of your clients’ stores as needed with no limits.

Also, Enterprise On-Premise solution includes webhooks, escrow service, WhiteLabel, and plugin builder.

Enterprise On-Premise solution is perfect for high-volume enterprises with a high number of clients.

To test API2Cart Enterprise On-Premise solution you will need to:

  1. Contact our manager by phone, email ([email protected]), or online chat. At first, you can test API2Cart functionality on https://app.api2cart.com/. If you decide to switch to Enterprise On-Premise Solution, you contact us, and we will create a separate server for you with no limits.
  2. We create infrastructure on Amazon. Enterprise On-Premise solution is placed on Amazon Cloud storage. It is possible to get access to it using our Amazon Web Services (AWS) or your own. Also, you can use the solution not only on AWS but also on Google Cloud, Microsoft Azure, Hetzner Cloud, or your own server.
  3. Get access to API2Cart using a particular link. API2Cart Enterprise On-Premise solution is available on a special link. Only your team will have access to it. Also, it can be a special subdomain (e.g., yourcompany.api2cart.com) or domain (api2cart.yourcompanydomain.com).
  4. Test the solution for 30-days for free. During the trial period, you will be able to connect an unlimited number of your clients’ online stores and use all API2Cart API methods for working with the data related to products, categories, customers, orders, shipments, etc.

The usage of API2Cart Enterprise On-Premise solution includes continuous support by our dedicated tech specialists.

Asymmetric data encryption has been added in version 141 of the bridge as well as plugins that can be built using the plugin builder. Data is encrypted using the OAEP (Optimal Asymmetric Encryption Padding) protocol, which provides reliable security and resistance to attacks.

When exchanging data between API2Cart and the server on which the bridge or plugin is installed, there is a risk of interception of this data. Especially if the data is not transmitted over a secure HTTP protocol, an attacker can gain unauthorized access to the database. In addition, if the attacker somehow learns the store_key, he can directly interact with the store through the bridge, bypassing API2Cart. To prevent this from happening, we implemented asymmetric data encryption.

Here's how it works:

  • when downloading a bridge or installing a plugin generated by the plugin builder, a pair of keys is generated: a public key for encryption (contained in the bridge file) and a private key for decryption (added and known only to API2Cart). Each new store will have an individual key.
  • data transmitted to the bridge is encrypted using a private key.
  • when receiving data from API2Cart, the bridge decrypts the data, and the bridge executes the necessary scripts.
  • the received results are encrypted using a public key and sent to API2Cart, where they are decrypted using a private key.

This algorithm does not lead to significant delays in the execution of requests or additional load on the server and is a reliable tool for protecting confidential data during its exchange between parties.

Its main advantages:

  • Encrypted communication channel prevents interception of confidential data.
  • Protection against store_key exposure; an attacker will not be able to perform requests directly to the bridge/plugin even if he knows the store_key.

The Plugin Builder allows you to build the Bridge Connector plugin, which is used to connect the store to API2Cart, for different shopping platforms. The following platforms are currently supported:

  • Magento 2
  • Opencart 2.x - 4.x
  • PrestaShop
  • Shopware 6
  • WooCommerce

If the “Plugin builder” feature is available in the account plan, the plugin can be customized to your needs, for example, you can specify the plugin's name, company, description, and logo. Also, you can enable or disable encryption on the bridge, configure the callback URL, etc. When this feature is unavailable in the plan, the values for the plugin are set by default.

Also, the possibility of asymmetric data encryption has been added to the Plugin Builder. Data is encrypted using the OAEP (Optimal Asymmetric Encryption Padding) protocol, which provides a reliable level of security and resistance to attacks. More details.

Callback URL and Public Key allow you to generate a plugin. After installing it and clicking the “Connect” button, a webhook will be sent to the URL that was specified in the Callback URL field with encrypted store credentials that can be used when adding it to APICart. Namely: store_url, store_key, store_root, bridge_url. Data is encrypted with an RSA key. You can insert your own public key or generate a pair of 2048-bit keys.

The data sent to the callback is encrypted according to the following principle:

  • Encoding the data array into a JSON string
  • Division of the received string into parts of one length (depending on the length of the generated key)
  • Encoding the parts with the public key
  • Combining the encoded parts into one string and converting it to base64 format
  • Sending the base64-encoded string to the callback

The callback will receive a webhook with encrypted data in the "data" field.

The x-webhook-cart-id and x-webhook-timestamp headers are also available.

To decrypt the data, you need to perform actions with the received data in the reverse direction:

  • Decode from base64
  • Division of the string into equal parts (depending on the key length)
  • Decrypt the received parts using the private key
  • Combine the obtained decrypted parts into a single JSON string

Here's an example of PHP code:

As a result, you will receive data that can be used in the account.cart.add method to add a store.

Some fields in the Pplugin Builder are validated, and an error will be displayed if incorrect data is entered. Also, next to each field is a hint with a brief description of what this field is for.

After successfully building the plugin, the downloaded archive with the plugin can be installed on the page of the selected platform.

Return (RMA, Return Merchandise Authorization) - return of low-quality or defective goods for repair, replacement, refund, etc. Only shipped goods can be returned.

The return process may vary depending on the specific eCommerce platform. However, the return procedure usually includes the following:

  1. The customer creates a return request, where he indicates the product he wants to return, the reason for the return, and the desired action (product replacement, repair, refund, etc.).
  2. Depending on the return policy of a particular online store, the seller can confirm or reject the customer's request.
  3. If the manager confirms the return request, the product is sent back to the seller.
  4. The seller performs an action (replaces the product, refunds, etc.).

First of all, you need to check in the API2Cart API Documentation whether there are methods for working with returns for your chosen eCommerce platform:

return methods api2cart

You should also read the method description to know which options are supported and required for a particular eCommerce platform.

Or you can use this link.

Returns are closely related to orders. Methods for importing (creating and updating) returns are in the order section. For greater filtering capabilities, methods for exporting returns are placed in a separate return section.

To create a return, you need to use the order.return.add method.

order return method

For all platforms, order_id and order_products must be specified. That is, which order and which products in the order will be returned.

In order_products, you need to specify the following:

  • order_product_id - the product ID in the order. The value should be taken from the export of orders (order.list/info)
  • order_product_id
  • order_product_quantity - number of product units to be returned.

Depending on the eCommerce platform, you must also specify:

  • order_product_reason_id return reason, the value must be taken from the return.reason.list method. Not supported on Bol.com.
  • order_product_customer_comment - the customer's comment describing the reason for the return. On some platforms, there may be a separate comment for each product, and on some, there may be one common comment for all products, in which case you need to specify the comment parameter.
  • order_product_handling_status - supported only on Bol.com. Is required. This is the processing status of the returned product. Possible values are displayed in the error text if an incorrect value is specified.
  • order_product_handling_status
  • return_status_id - return status, the value must be taken from the return.status.list method.

The return status can be updated using the order.return.update method.

order.return.update method

You can't specify any return status on Shopify. Shopify has a clear return workflow. Follow this chart to find out which status you can upgrade to.

return status on Shopify

A list of all returns can be obtained with the help of return.list method.

For Shopify, you must specify the order_id or order_ids parameter. That is, on Shopify, you can only issue returns for a specific order.

In order to find out for which orders there are returns, you need to select the value from the export orders field additional_fields -> return_status.

return_status

If the value is no_return, then no return request was created for such an order. Accordingly, return.list will not return anything for such an order. If the status is any other, then in this case, a return will be displayed for the order.

For Shopify, there is a return_status filter in the order.list method that allows you to filter orders for which there is a return.

We provide a unified API to work with multiple shopping carts and marketplaces. By integrating with our API, you can integrate with different e-Commerce platforms such as Magento, PrestaShop, Bigcommerce, Shopify, OpenCart, Volusion, etc. at the same time, without any need to develop separate integration solutions for each shopping cart.

The integration works the following way - you already have your business logic module which is integrated with API2Cart. Thus, you receive a complex solution which can work with numerous platforms - hosted and self-hosted. You will have to establish connection via connection bridge or provide store access details - and you'll be able to retrieve necessary data and process it with your solution. So, API2Cart is a universal programming interface which will help you optimize eCommerce integration process.

Lately announced, all WooCommerce users are able to upgrade their stores to the new 4.0 version. However, there are profound changes considering orders.

Make sure you have performed WooCommerce upgrade correctly to allow WooCommerce and API2Cart work with your orders properly.

There are two ways to establish WooCommerce upgrade:

  1. Automated. Just press “Update Now” button and all needed changes will be done correctly.
  2. Manual. Update all WooCommerce files via your FTP client. In this case, after upload, you have to click “Run Installation” in your admin panel.

Notice that only after that, database version is updated. Otherwise, you won’t be able to view the previously placed orders in WooCommerce itself. And API2Cart will not be able to detect new WooCommerce version, thus work with new orders.

Check the following steps to add API2Cart IPs to whitelist and prevent accidental blocking.

Instruction for WHM (Web Host Manager)

1. Login to WHM (Web Host Manager)

whm-login

2. Go to Security Center and then Host Access Control.

3. Add IP addresses over the ALL deny line in Host Access.

Host-Access-control

4. To ensure the IPs won’t be banned by cPHulk, add them to the white list.

cPHulk-whitelist

5. If there is the CSF plug-in installed, do not forget to add СSF IP to the white list as well.

СSF-IP-whitelist

Instruction for Plesk user:

  1. Login to Plesk.
  2. Click Websites & Domains tab at the top.
  3. Click SQL Whitelist Beta icon.
  4. Click Add IP, select service and type IP; Click OK.

The list of IPs you need to add:

  • 144.76.201.51

When the registration is completed, you are automatically redirected to your API2Cart account. In the “My Stores List” section you will find OpenCart demo store which is available for testing service’s functionality.

You can also add demo stores that can be created in the "Demostores" section of your API2Cart account. More details at Demo store in API integration

Many shopping carts have an entity limit in one request. Even if it is said that there is no limitation, you should be careful and not to include too many entities in a single API request since it may negatively affect your system and client’s store performance. It is better to extract data in smaller chunks (4­-50 items), what guarantees a correct result.

Notice that:

  • BigCommerce limits the number of entities to 250 in a single API request.
  • 3DCart has no official limits set but after the various requests test it is recommended not to exceed 100 entities.
  • Shopify’s entity limit includes 250 in one request.
  • Volusion has no limitation. However, we recommend not to include more than 50-100 entities.

It all depends on the speed of connection and your shopping cart server, as well as the type of shopping cart. For example, the requests for Magento take more time than for the shopping cart like osCommerce. While retrieving data from shopping cart specify the necessary fields in the parameters. This will speed up the process. Do not specify the unnecessary fields, because for some fields additional requests may be sent, which increases the time of data retrieving.

Our developers are constantly improving the service to provide its fast and reliable performance.

API2Cart uses Customer.list API method that help to retrieve following data:

  • Customer ID
  • Customer Group
  • Customer’s e-mail
  • Customer First Name
  • Customer Last Name
  • Time of customer creation
  • Time of customer modification
  • Customer’s login
  • Date of last login
  • Customer’s date of birth
  • Customer Status
  • Customers subscribed for newsletters
  • Customer’s Gender (male/female)
  • Link to use website
  • Customer’s fax number
  • Customer’s Company
  • Customer’s phone number
  • Customer’s Address Book

This method also includes the fields that were created in the shopping cart backend (admin section) and the specific fields, which are set for this shopping cart by default.

API2Cart constantly improves its services, so we expect to deliver you all the required methods in the near future. Please contact us in order to request necessary functionality.

Connection Bridge file is what helps API2Cart users connect stores which are based on open-source shopping platforms like Magento, WooCommerce, PrestaShop, and CS-Cart. API2Cart API works directly with databases of such types of shopping platforms via a bridge file. Read more.

We use the minimum amount of code in our bridge files. Running SQL queries allows us to retrieve the data directly without running all the shopping cart code. What is more, the bridge allows us to work with the data that is not available via the platform’s API.

Benefits of the Connection Bridge:

- Speed

- Low server load, because all data is processed on our side.

- Flexibility, as we can add new methods without updating the bridge.

This special access gateway is secured by the unique signature and encryption for safe data processing. To add a store to your API2Cart account you have to set up Connection Bridge to enable data interaction.

There are three ways you can connect Bridge file:

1. Manually download the Bridge to your computer. It will be stored in a zip file named “bridge.zip”. Extract the file. It will contain the “bridge2cart” folder. Upload it to the store’s root folder via FTP client (WinSCP, FileFTP, FileZilla, CuteFTP, etc.)

If needed, the bridge file can be stored in any folder on the server, but in that case you’ll need to use parameters bridge_url (the full http url for a bridge) and store_root (absolute server path to the store root folder).

If the bridge folder is contained in the store root folder, then you don’t need to specify store_root parameter, only bridge_url.

After uploading the bridge, use account.cart.add method.

2. Automatically upload the Bridge via account.cart.add method. Use account.cart.add method specifying FTP credentials (Host, Port, Login, Password and Store Path) or use API2Cart admin panel.

3. Using plugins that can be built in the Plugin Builder section on your API2Cart account.

What is the Connection Bridge and why do I need it?

Plugin uploads the bridge and installs it to the store’s root folder. You can place the plugin on the platform app marketplace. Then, your clients will be able to install the bridge in one click.

To check if the Connection Bridge file has been installed correctly enter https://[yourstore url]/bridge2cart/bridge.php within your browser address line. If the bridge file is working correctly, you will see the following message:

“Version: xx

BRIDGE INSTALLED.”

Check the current bridge version here.

If not, please set the following permissions:

- 644 or 666 for "bridge.php", depending on your server configuration

- 755 or 777 for "/bridge2cart" folder, depending on your server configuration

Note! We strongly recommend turning off your website redirects to ensure proper functioning of the Connection Bridge file.

If you have any questions during the process of bridge installation, please read this article or contact us by email ([email protected]).

API2Cart supports Product.list API method that helps to retrieve the following data from the shopping cart:
  1. Product ID
  2. Brand name of product
  3. Product Model
  4. Product SKU
  5. Universal Product Code
  6. Time of product creation
  7. Time of product modification
  8. Product Name
  9. Product short description
  10. Product full description
  11. Product URL
  12. Product SEO URL
  13. Product meta title
  14. Product related keywords
  15. Product meta description
  16. Product available for sale
  17. Products available for view
  18. Count of products views
  19. Count of products ordered
  20. Product Weight
  21. Product Quantity
  22. Product Price
  23. Price of products sold in large quantities (wholesale)
  24. Special price of product. ex. Regular price:100 Special Price: 99.99
  25. Price with discount based on the ordered product quantity
  26. Product category IDs
  27. Product Categories
  28. Product Images
  29. Product Options
Product.list method also includes the fields that were created in the shopping cart backend (admin section) and the specific fields, which are set for this shopping cart by default. API2Cart constantly improves its services, so we expect to deliver you all the required methods in the near future. Please CONTACT US in order to request the necessary functionality.

You can use the parameter force_all (for example, product.list?api_key=<your_api_key>&store_key=<your_store_key>&start=0&count=10&params=force_all.) or use the response_fields parameter, which will contain the result field (for example, order.list?api_key=<your_api_key>&store_key=<your_store_key>&start=0&count=10&response_fields={return_code,return_message,pagination,result}).

For more information go to API2Cart Documentation.

FTP access is specified for automated uploading store bridge, which will be used for connection.The bridge can be uploaded automatically, specifying FTP access or manually, saving the bridge file. For that you have to click Download in the appropriate form and upload a bridge to the root of your store and click Save.