BigCommerce

BigCommerce is the leading e-commerce platform for running an online store.

Data integration: Skyvia supports importing data to and from BigCommerce, exporting BigCommerce data to CSV files, replicating BigCommerce data to relational databases, and synchronizing BigCommerce data with other cloud apps and relational databases.

Backup: Skyvia Backup supports BigCommerce backup.

Query: Skyvia Query supports BigCommerce.

Establishing Connection

Skyvia supports connecting to BigCommerce using legacy Basic authentication and OAuth authentication (using Store Credentials). Connections with OAuth authentication using App Credentials cannot be manually created by the user.

Basic authentication is not supported for API v3 connections. BigCommerce strongly recommends using OAuth authentication. Basic authentication support is left in Skyvia for compatibility purposes for API v2 connections.

Getting Credentials

Parameters for OAuth (Store Credentials) Authentication

To get parameters for OAuth authentication using Store Credentials, you must create an API user. For this, perform the following actions:

1. Sign in to your BigCommerce Control Panel.
2. In the menu on the left, click Settings.

3. Scroll the settings page down and click API Accounts.

4. You can see a list of API accounts displaying the assigned scopes. To create a new account, click + Create API Account.

   Required parameters are displayed only once when creating an API account. It’s not possible to view these parameters for an already created account. If you do not have the parameters for an existing account stored anywhere, the only way to obtain them is to create a new API account.

   

5. Specify the API user name and select the necessary OAuth scopes to allow Skyvia access. You can find available OAuth scopes in the BigCommerce documentation.

6. Click Save. The necessary connection parameters are displayed and automatically downloaded as a text file. In Skyvia, you need a client ID and access token from there. Be sure to store these parameters somewhere, as you won’t be able to see them for this API account anymore.

Parameters for Basic Authentication

You can get parameters for basic authentication by viewing them for your legacy API accounts. To do it, perform the following steps:

1. Sign in to your BigCommerce Control Panel.
2. In the menu on the left, click Settings.

3. Scroll the settings page down and click API Accounts.

   

4. A list of API accounts displaying the assigned scopes opens. Scroll it down to the bottom. At the bottom of this list, click the Click here link in “Click here to access existing legacy API accounts.”.

   

5. A list of legacy accounts is opened. Click the three-dotted button for the required account, and then click Edit.

6. Copy the required API Path and API Token.

   

Creating Connection

OAuth Authentication

To connect to BigCommerce, using OAuth authentication (Store Credentials), you need to set the following parameters:

1. Select the API Version to use — v2 or v3.
2. Select Store Credentials for Authentication parameter to use the OAuth authentication.
3. Specify the Store Id — store hash from the API Path. For example, when you log in to your BigCommerce store Control Panel, an URL similar to the following opens in your browser: https://store-kj3jh4c.mybigcommerce.com/manage/dashboard. The part of the URL highlighted in bold is the store Id required.
4. Specify the Client Id — Client Id of your API account.

5. Insert the Access Token — OAuth access token to log in with.

   

Creating a connection using App Credentials authentication manually is not possible.

Basic Authentication

Basic Authentication is considered deprecated. It uses BigCommerce legacy API accounts that cannot be created in new BigCommerce stores created after July 31, 2018.

To connect to BigCommerce, using basic authentication, you need to specify an URL to connect to and a user name and authentication token to log in with.

You need to specify the following parameters for a basic authentication connection:

1. Select API Version. Only API v2 supports basic authentication.
2. Set Basic for the Authentication.
3. Specify the URL. API Path (the path where all XML requests to BigCommerce should be sent).
4. Specify the User Id — user name to log in with.
5. Insert the Authentication Token — an automatically generated key that is used and that must be included in the API requests to BigCommerce.

Additional Connection Parameters

Use Custom Fields

This checkbox is available only for BigCommerce API v3 connections. It determines whether you will be able to get product custom fields via the CustomFields field of the Products object through this connection. If this checkbox is selected, this field returns a JSON array containing information about custom fields and their values for products, if such are available. Otherwise, it always returns null values.

This checkbox does not affect working with custom fields for Customers and CustomerAddresses, and it also does not affect access to Product custom fields via the ProductCustomFields object.

Processing custom fields may take additional time and API calls, so it’s recommended to select this checkbox only if you need to work with Product custom fields via this connection.

Connector Specifics

BigCommerce API Versions Support

Skyvia supports both BigCommerce API v2 and API v3 connections.

The lists of objects and their structure is different for BigCommerce API v2 and API v3. The main differences are connected with objects, storing data about products, their variants, options, prices, brands, etc.

Here are the lists of objects that are supported via API v3 and, thus, have different data structures in API v2 and v3 connections:

The objects present in both columns have clear counterparts in API v3 and v2 and have just different internal structures. However, product options have a completely different structure, and the objects storing them do not have such clear counterparts.

Besides, BigCommerce API v3 provides access to new objects not available via API v2:

ProductMetafields, ProductVariantMetafields, PriceLists, PriceListRecords, ProductModifiers, ProductModifiersValues, CatalogSummary, CategoryTrees, Channels, CustomerFormFieldValues, CustomerAddressFormFieldValues, CustomerAttributes, Carts, CartLineItems, CartCustomItems, CartGiftCertificateItems, CartMetafields, SystemLogs, TaxRates, TaxZones, TaxProperties.

Other BigCommerce objects are accessed via API v2 in both API v2 and API v3 connections.

Object peculiarities

Read-only Objects

The following BigCommerce objects are read-only: BlogTags, Countries, CustomerAddressCustomFields, CustomerCustomFields, OrderCoupons, OrderMessages, OrderProductOptions, OrderProducts, OrderShippingAddresses, OrderStatuses, OrderTaxes, PaymentMethods, ProductConfigurableFields, ProductGoogleProductSearch, ProductOptions, ProductReviews, States, Store, SystemLogs, TaxClasses.

Related Objects

Some of the BigCommerce objects can be accessed only via their parent objects. For example, to query ProductCustomFields, BigCommerce API requires the Id value of the corresponding Product record.

Skyvia does not require this Id of the parent object from the user. If you don’t specify the Ids of the parent objects (for example, in a filter), Skyvia queries all the parent object records first, takes their Ids, and then queries child object records for each parent object record. This allows querying child objects without knowing their parents, but this method takes much time and consumes many API calls. It uses at least one API call for every parent object record (for example, product). Thus, working, for example, with ProductCustomFields, can be slow.

Thus, it is recommended to use filters on the parent object fields when querying data from such child objects. This reduces the number of parent object records for which child object data must be queried.

Complex Structured Data

Some of the BigCommerce objects store complex structured data. These are the following objects: Orders, OrderShipments, Customers, CustomerAddresses, Carts, TaxRates and other objects, that have custom fields, and some other nested objects and arrays.

For example, an order can have several lines and several shipping addresses. Skyvia represents this information in such objects as fields in the JSON format. In case of Orders, the fields are named Products and ShippingAddresses. Here is an example of the Products field value from the Orders object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
    [
      {
        "Id": 37,
        "ProductId": 77,
        "Name": "[Sample] Fog Linen Chambray Towel - Beige Stripe",
        "Sku": "SLCTBS-70D1759E",
        "PriceExTax": 49,
        "PriceIncTax": 49,
        "Quantity": 1,
        "ProductOptions": [
          {
            "Id": 29,
            "OptionId": 18,
            "OrderProductId": 37,
            "ProductOptionId": 108,
            "DisplayName": "Size",
            "DisplayValue": "L",
            "Value": "71",
            "Type": "Multiple choice",
            "Name": "Apparel sizes",
            "DisplayStyle": "Rectangle"
          },
          {
            "Id": 30,
            "OptionId": 3,
            "OrderProductId": 37,
            "ProductOptionId": 133,
            "DisplayName": "Color",
            "DisplayValue": "Yellow",
            "Value": "12",
            "Type": "Swatch",
            "Name": "Colors"
          }
        ],
        "OrderId": 128,
        "OrderAddressId": 36,
        "Type": "physical",
        "BasePrice": 49,
        "PriceTax": 0,
        "BaseTotal": 0,
        "TotalExTax": 49,
        "TotalIncTax": 49,
        "TotalTax": 0,
        "Weight": 0,
        "BaseCostPrice": 0,
        "CostPriceIncTax": 0,
        "CostPriceExTax": 0,
        "CostPriceTax": 0,
        "IsRefunded": false,
        "RefundAmount": 0,
        "ReturnId": 0,
        "BaseWrappingCost": 0,
        "WrappingCostExTax": 0,
        "WrappingCostIncTax": 0,
        "WrappingCostTax": 0,
        "QuantityShipped": 0,
        "FixedShippingCost": 0,
        "OptionSetId": 14
      }
    ]

For user convenience, lines of these objects are also available as separate records via read-only objects with names containing the name of the corresponding parent object and its JSON fields: OrderShippingAddresses, OrderProducts, OrderProductOptions, CustomerCustomFields, etc.

Since these objects (presenting JSON data in table form) are read-only, they are not available in Import packages as a target or in Synchronization packages. To modify lines or shipping addresses of orders, etc., you need to provide values in JSON format for the corresponding field of the corresponding main object — Orders, etc.

These objects are available in Backup packages, but you cannot restore data to these objects because they are read-only. Since they store the same information as the corresponding field of the corresponding main objects, you don’t actually need to back them up. All the information in such objects is present in the corresponding main objects, and you can back up and restore data in the main object only.

Custom Template Association Objects

CustomTemplateAssociations object stores all associations of Stencil themeʼs custom templates to products, categories, brands, and pages. EntityId and EntityType fields store the IDs of the corresponding entities and their type: product, category, brand, or page. We strongly recommend filtering by both EntityId and EntityType fields when querying data from this object.

There are additional objects in our BigCommerce connector, which were added for user convenience to reduce API call use when querying. These objects store template associations separated per type of associated records: ProductTemplateAssociations, CategoryTemplateAssociations, BrandTemplateAssociations, PageTemplateAssociations. Use them to get the template association of the specific type. These objects store the entity ID in the ProductId ,CategoryId , BrandId, PageId fields, respectively.

Wishlists

BigCommerce Wishlists object also has a similar field Items with a JSON array of wishlist items. When you create a new record in this object, you need to specify its value as a JSON array as well as for the previously mentioned objects. However, the object of its items - WishlistItems is not read-only, and you can update existing wishlists by adding or deleting records to the WishlistItems object. The Items field of the Wishlists object is not available for the UPDATE operation.

Categories

If you use the Multi-Storefront feature, you can add categories to the specific catalog tree. When mapping, specify the tree ID in the TreeId field. If you don’t know the ID of the tree, you can find it in the CategoryTrees object.

When adding the root category with no nested categories, set the ParentId field to 0.

Channels

When you import records to this object, you must specify the valid values from the list for the Type, Platform and Status fields.

When importing records to the Channels object, you must use valid type and platform combinations. Find the valid combinations in the table below.

Allowed values for a channel’s status vary by channel type and platform. Use the valid combinations listed below.

Customers

This object has a complex structure. The Channels, FormFields, Attributes, and Addresses fields contain nested objects. They are text fields in JSON Array format.

You can insert not more than 10 array items into the Attributes and Addresses fields. Use the child CustomerAddresses and CustomerAttributes objects for importing more items once.

CustomerAddresses

This object has a complex structure. The FormFields field contains the nested objects. It is a text field in JSON Array format.

The AddressType field accepts the following valid values: residential and commercial.

CustomerAttributeValues

When updating records in this object, we recommend mapping the Id, CustomerId, and AttributeId fields. It will increase performance significantly.

Carts

Use filter by Id to select data from the Carts object.

The LineItems, GiftCertificates, CustomItems, Coupons, and Discounts contain the nested arrays. These fields are text fields in the JSON Array format.

When you create a cart, it must not be empty. It requires mapping at least one of the following fields for successful data import. Map the LineItems field when adding a cart with products. Map the GiftCertificates field when adding gift certificates. Map the CustomItems field when adding custom items.

You must specify at least the product ID and quantity in the LineItems field to create a record in the Carts object successfully. For example, [{ProductId:35018, Quantity:1}].

If the product demands choosing a variant (for instance, it requires selecting size or color before checkout), you must specify the product variant Id in the LineItems field. For instance, [{ProductId:35018, VariantId: 34963, Quantity:2}].

If you add custom items to the cart, you must specify at least the item SKU, name, quantity, and price in the CustomItems field. For example, [{Sku:"Sku-custom-beer", Name:"Beer", Quantity: 3, ListPrice: 5.5}].

When you add a cart with a gift certificate, you must specify the certificate name, theme, quantity, amount, sender name, email, recipient name, and recipient email. For example, [{Name:"My Day",Theme:"Birthday", Quantity:1, Amount: 25, SenderName: "Jon", SenderEmail: "[email protected]", RecipientName: "Jim", RecipientEmail: "[email protected]", Message: "Hello"}].

For user convenience, the data from the LineItems, GiftCertificates, CustomItems fields are represented in Skyvia as separate auxiliary objects: CartLineItems, CartGiftCertificateItems, and CartCustomItems. You can use these objects for data import. For example, you can add lines to the existing carts using them.

CartLineItems

Use filter by the CartId field to get data from this object successfully.

The fields GiftWrappingTogether and GiftWrappingId are used for data import only. They return empty results by default when querying.

The CartLineItems object has the Options field, representing an array of additional product options. Use this field for cases when a product has options but not variants. It is useful when the product was created using API V2 or when there are additional options (product modifiers) from the seller, not the manufacturer.

For example, the Options field looks like this [{"NameId":240,"ValueId":98,"Name":"test2","Value":"test2"}]. The NameId indicates the option ID, and the ValueId indicates the option value ID. You can find these IDs in the ProductModifiersValues object.

You can omit the Options field if the product has variants.

When updating the CartLineItems object, you must map the ProductId and the required Id and CartId fields.

CartCustomItems

Use filter by the CartId field to get data from this object successfully. We also recommend filtering by the Id field for better querying performance.

To successfully insert data to this object, map the CartId, Sku, Name, Quantity and ListPrice when importing data.

CartGiftCertificateItems

Use filter by the CartId field to get data from this object successfully. We also recommend filtering by the Id field for better querying performance.

The Themes field accepts the following valid values: Birthday, Boy, Celebration, Christmas, General, Girl.

To successfully insert or update data in this object, specify the following fields: CartId, Name, Theme, Quantity, Amount, SenderName, SenderEmail, RecipientName, RecipientEmail.

CartMetafields

Use filter by the CartId field to get data from this object successfully. We also recommend filtering by the Id field for better querying performance.

The PermissionSet accepts the following valid values: app_only, read, write, read_and_sf_access, write_and_sf_access.

To successfully insert data in this object, specify the fields: CartId, PermissionSet, Namespace, Key, Value. The Key indicates the name of the field. The Value indicates the value of the field.

TaxRates

To successfully import data to the TaxRates, you must map the Name, TaxZoneId and ClassRates fields.

This object has a complex structure. The ClassRates is a text in JSON Array format. The ClassRates array contains two fields TaxClassId and Rate.

For example, the ClassRates field value looks like this [{TaxClassId:0, Rate:4.5 }].

TaxZones

This object has a complex structure. The Locations field is a text in JSON Array format. It contains the CountryCode and the array fields: SubdivisionCodes and PostalCodes. The CustomerGroups field is an array of customer group IDs, for example [13279,13280].

ProductTaxProperties

When you perform the DELETE operation, BigCommerce API allows deleting all tax property values from a product. It doesn’t allow deleting single property value.

TaxSettings

BigCommerce API allows only updating the existing records in this object. You can’t insert or delete records from this object.

The InvoicePriceDisplayStrategy field accepts the following valid values: ZONE, INCLUSIVE, EXCLUSIVE.

The FallbackStrategy field accepts the following valid values: FIXED, BASIC, DISABLE.

Incremental Replication and Synchronization

Replication with Incremental Updates enabled is supported for the following objects: BrandMetafields, Carts, CartLineItems, CartMetafields, CategoryMetafields, Channels, Customers, CustomerAttributes, CustomerAttributeValues, _OrderMessages, OrderShipments, OrderMetafields, Orders, PriceLists, PriceListRecords, ProductImages, ProductMetafields, ProductReviews, Products, ProductVariantMetafields, Subscribers, SystemLogs, TaxProperties, Transactions. The OrderMessages, OrderShipments and Transactions objects have the CreatedDate field and do not have the DateModified field. It means that only new records can be replicated.

Synchronization is supported for the following objects: BrandMetafields, Carts, CategoryMetafields, CartMetafields, Channels, Customers, CustomerAttributes, CustomerAttributeValues, OrderMetafields, Orders, PriceLists, PriceListRecords, ProductImages, ProductMetafields, ProductReviews, Products, ProductVariantMetafields, Subscribers, TaxProperties.

DML Operations Support

Skyvia supports the following DML Operation for BigCommerce:

Supported Actions

Skyvia supports all the common actions for BigCommerce.