General Service Questions

Do you support real-time synchronization?

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.

How to work with Live Shipping Rates

We return Live Shipping Rates on Shopify and WooCommerce for now (April 2019)

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.

 

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 http://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.

How to Create FTP Credentials

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

Do you provide integration between two services using their public API?

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.

How to upgrade WooCommerce correctly?

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.

How can I add API2Cart IPs to whitelist?

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

I would like to test your service. Do you have any test stores?

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.

Is there an entity limit in single API request?

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.

Why API methods may perform slowly?

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.

What customer information can I work with while using API2Cart?

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.

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

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 type of shopping platforms via a bridge file. Read more.

 

We use the minimum 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 proceeded on our side.

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

 

This special access gateway is secured by the unique token 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 two ways you can connect Bridge file:

 

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

 

If needed, bridge file can be stored in any folder on 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 cart.create method.

 

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

For this, press the button “Add store” in your API2Cart admin panel and check the box “Please upload bridge to my store” and provide your FTP credentials.

connection bridge shopping cart integration

To check if the Connection Bridge file has been installed correctly enter http://[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 to turn off your website redirects to ensure proper functioning of the Connection Bridge file.

What product details can I work with while using API2Cart?

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 necessary functionality.

Where can I find the list of all fields, which I can get with my cart when performing product.list, product.info methods?

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 you can use product.fields method.

For more information go to API2Cart Documentation.

Here you can find all the fields descriptions.

Why is it necessary to specify FTP access when adding a store?

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.

Need help or advice?

Schedule a call