bigcommerce / dev-docs

This repo contains the markdown files and static assets powering developer.bigcommerce.com. https://developer.bigcommerce.com/

BigCommerce Developer Documentation

As of December 27, 2023, you can find all the public BigCommerce DevDocs at https://github.com/bigcommerce/docs!

This repository is archived and read only. The final commit has been tagged.

This consolidation lets the BigCommerce DX team offer a more streamlined developer experience. We look forward to seeing your issues, discussions, and pull requests at bigcommerce/docs!

dev-docs's Issues

Feedback for “Getting Started with the BigCommerce REST API”

I hate the new docs!!!!! Where is the testing ability? Where are the examples? WTF?!?!? this sucks

No documentation for `{{each}}` in the Handlebars Helpers Reference

{{each}} is used in examples of the Handlebars Helpers Reference; however, it's not actually documented anywhere in the document.

Somewhat related, the number of helpers for loops is a little overwhelming, could be useful to have a somewhere that helps users choose which one to use. (There's each, eachIndex, forEach, forOwn, forIn, and iterate from what I could see)

Feedback for “Introduction to Headless Commerce”

Hi, this is probably a more sales oriented question. I'm uncertain if this is the right place. But I could not easily find an answer on your site.

Do all plans offer Headless Ecommerce?

We have a successful Gatsby/React Site and would like to add cart/checkout/payment functionality. Does Pro Plan offer API access?

Thanks,
Stefan

Feedback for “Custom Templates”

“ After editing your .stencil or config.stencil.json files (if you are using Stencil V3.1 release or later), you must restart the Stencil app to view your changes locally. To restart stencil, type stencil start at a command prompt, and append the appropriate switches for your workflow, for example: stencil start -e -n.”

This tells me that “AFTER” I’ve edited my config file, but it doesn’t explain in any way (nor does it provide a link) for how I’m supposed to edit the config file. This is yet another example of the documentation author (or authors) assuming that the reader knows something that we don’t know yet. It shouldn’t be a problem for the author(s) to include links to documentation/explanation of what is contained in the documentation. This makes it incredibly frustrating to try to learn and understand how to create/modify themes and just generally understand Stencil and how Big Commerce works.

I attempted to find additional documentation for how I’m supposed to modify the config files when creating custom templates, so I searched for config.stencil.json in your stencil documentation search, and the only thing returned was config.json: https://developer.bigcommerce.com/theme-objects/config-json1st and then something about widgets (which wasn’t relevant). the link for `config.json wasn’t helpful either. I could not find anything that explained what I need to change in the config.stencil.json file when creating a custom template.

I took a look at the config.stencil.json file and there is a JSON object (“customLayouts”) that I’m assuming is the thing that I need to modify, but I have absolutely no idea what I’m supposed to put in the slots provided.

Feedback for “Promotions Single”

I think this page is broken.
There is no detail about what is needed in the body to update.
The previous API listed the properties.

Test

Test

I can't create a custom widget through the API

I'm following the widgets tutorial, but although they are displayed in Page builder, the widgets are not working, it doesn't display something in the preview and design views.

Also, I reviewed other examples but I get the same result, the widget is empty.

Here is my code:

widget template

{
  "name": "List",
  "template": "<ul>\r\n{{#each list_items}}\r\n <li style=\"color:{{color}};\">{{text}}<\/li>\r\n{{\/each}}\r\n<\/ul>",
  "schema": [
       {
      "type": "tab",
      "label": "Content",
      "sections": []
       }
    ]
}

widget

{
  "name": "Simple List Test",
  "widget_configuration": {
    "list_items": [
      {
        "color": "blue",
        "text": "The color is blue"
      },
      {
        "color": "green",
        "text": "The color is green"
      },
      {
        "color": "red",
        "text": "The color is red"
      }
    ]
  },
  "widget_template_uuid": "UID TEMPLATE"
}

I really appreciate any help you can provide

restrict_to values in coupons not typed consistently

When there is nothing in the restricted_to value for the coupons endpoint I get back an empty array, but when there is something I get back an object that contains key "countries" that holds an array of strings. The empty value of restricted_to should be an empty object not an empty array.

Feedback for “Checkout SDK”

https://developer.bigcommerce.com/stencil-docs/customizing-checkout/checkout-sdk#required-payment-method-initialization-options

Link results in 404

Improve docs for customFields at /checkouts/{checkoutId}/billing-address

Hey there,

the docs or schema at https://developer.bigcommerce.com/api-reference/store-management/checkouts/checkout-billing-address/checkoutsbillingaddressbycheckoutidpost says that the field for custom fields is called "custom_fields". When using "custom_fields" you'll get a HTTP 500 response. It only works if the field is called "customFields".

Please improve the docs so that is shows the right field name (customFields).

Cheers
Christian

Feedback for “Locations”

Hello, the sample post doesn’t work without wrapping the whole thing in [ and ].

{
"status": 422,
"title": "JSON data is missing or invalid",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"": "error.expected.jsarray"
}
}

Feedback for “Add to Cart URLs”

These codes don't work on our site. I've tried several variations of the url strings provided, and none of these results in this sku being added to cart.

https://www.calpaclab.com/cart.php?action=add&sku=CPLS-LANYARD
https://www.calpaclab.com/cart.php?action=buy&sku=EF-4-38
https://www.calpaclab.com/cart.php?action=buy&sku=CPLS-LANYARD&couponcode=WELCOME10

Create Product schema and examples are misaligned

There is an example request called "Creating a Product with Variants" that shows an option_values member of each variant object. However, this does not appear in the request schema. I started fiddling with it in Stoplight Studio, but started wondering whether option_values are appropriate for the PUT and GET requests for the product endpoint as well. Particularly GET.

test

test

Following documentation to build a Next.JS app downloads incorrect package.

Following the instructions on your 'Build A Next.JS Sample App' tutorial located here, in step 2 it asks for you to install node-bigcommerce.

Doing so, incorrectly, gives you this package. Which in theory would be fine, minus the fact that going down a few steps and running your code with this package will provide the error of bigcommerceSigned.verifyJWT is not a function.

The verifyJWT function was recently added in the bigcommerce/node-bigcommerce repo.

Currently, to get around this issue, I just installed the BigCommerce package directly from the repo with npm install https://github.com/bigcommerce/node-bigcommerce

I'm not 100% sure if this is something on my end, but once doing that, everything works as intended.

There's a merge conflict that's merged into the documentation for Multi-Language-Checkout

On the page https://developer.bigcommerce.com/stencil-docs/localization/multi-language-checkout you can see that two versions of some content exist along with the markers of a merge conflict that weren't removed from the file.

Feedback for “Stencil Technology Stack”

https://developer.bigcommerce.com/stencil-docs/getting-started/stencil-technology-stack

You provide a link to the Banner object documentation and then show an example of how it’s used in JSON. However, your example includes a top_metadata section that does not appear in the banners documentation.

Feedback for “Installing Custom Checkouts”

This documentation page shows 404:page not found error. Plz repair that page.

Feedback for “Management APIs”: Postman Collection download is gone

Before the recent update, you could download postman collections.

This feature is documented here: https://developer.bigcommerce.com/api-docs/getting-started/making-requests#import-api-spec-file-with-postman

This is a key feature. There are so many API routes that it's simply not feasible to create this manually.

While i'm here, it would be great if we could export one postman collection containing all routes, rather than needing to do it a category at a time, and merging them into one collection within Postman.

Feedback for “Embedded Checkout” | How to embed checkouts on not-logged-in customers buy experiences ?

How to embed checkouts on not-logged-in customers buying experiences ?

On the Embedded Checkout tutorial, as explained, in order to embed the checkout we need first to "Redirecting a logged-in customer to embedded checkout" but there is no clear path for checkouts of non-logged-in customers.
I will like to know how could be provided an alternative for client's that don't want to create an account to complete their purchase.

Missing schema docs tree for "Simple Item Matcher" object in Promotions API reference

Under the Body subheading of this section on creating a single promotion, there is missing information under rules > action > cart_items > items. When selecting Simple Item Matcher beside "One of", the schema of what I assume should be an object type is not displayed. So I have no idea what exactly is supported in this area of the API aside from what little information I can glean from the available code samples.

Feedback for “Overview”

Links from the Overview tiles on https://developer.bigcommerce.com/api-docs/overview result in 404-Page not found errors.
Examples:

• https://developer.bigcommerce.com/api-docs/building-apps/apps-quick-start
• https://developer.bigcommerce.com/api-docs/multi-storefront-implementations/msf-api-guide
• https://developer.bigcommerce.com/api-docs/building-channels/guide/building-channel-apps

Running `grunt textlint` causes GitHub rate limits

As advised in the contributing guide, running grunt textlint causes Github API Rate Limits to be applied to your account, the command ultimately fails. This looks like it relates to the no-dead-link check.

.../dev-docs/docs/stencil-docs/storefront-customization/using-front-matter.md
  94:129  error  https://github.com/bigcommerce/cornerstone/blob/master/templates/pages/product.html is dead. (429 too many requests)  no-dead-link

Cannot see Widgets locally

Recent project required creation of multiple widgets, but was disappointed to see that you can only view them on a live store/theme editor. Is there a way to view this locally during development?

Payment Processing

how to connect payment apis with a nextjs application that is inside the store in bigcommerce?

Feedback for “Introduction to Headless Commerce”

Headless Integrations links out to a dead page. I think we're meaning for it to redirect to https://developer.bigcommerce.com/tools-resources/tools

Test

Page:
Details: Aom

Example Request Payload for Storefront API - "Add Line Items to Cart" are incorrect - requires snake_case not camelCase

This example payload in the BigCommerce API Reference for the Storefront Carts API is incorrect:

Screenshot
https://www.screencast.com/t/SFferOPpij

This should all be snake_case instead of camelCase:

Correct:

option_selections: [{ option_id, option_value}]

Incorrect:

optionSelections: [{ optionId, optionValue }]

Order transaction docs are in bad format, and missing APIs

No order transaction get api anymore. Also void and capture are missing.

The table is badly formatted.

Feedback for “Listening for Events”

The "Webhooks Overview" link is dead: https://developer.bigcommerce.com/api-docs/getting-started/webhooks/setting-up-webhooks
Resources > Related Articles

Should be: https://developer.bigcommerce.com/api-docs/store-management/webhooks/about-webhooks

Feedback for “Embedded Checkout”

Can you please expand on the embedCheckout method and show where/how you're expecting the function to be imported into the code, covering all possible versions.
Thanks

Feedback for “Catalog Overview”

Key information regarding product->variant inheritance and updating products is missing from this documentation, and is also not mentioned in the API reference.

There is just an oblique mention that variants, "Can have their own price, weight, dimensions, image, etc. - or they can inherit these values from the product if you have not specified them."

What value should variant_price (or other variant fields) be set to in order to make it inherit the price from the product? My understanding is that if it is null or left out of the API call, then it is not changed.

Does updating price on the product automatically override the variant_prices? If not, which prices get overridden?

I'm hoping you can add this information to the documentation. Thank you!

Feedback for “Tools”

sdfasdfsdafsdf

What’s missing in your documentation

If there were just a short section that described how it all fits together - how to think about all of it: stencil, handlebars, the console, apps, etc. etc. etc.

The most difficult thing that I have found about trying to learn from your documentation is that, usually, there is some idea or concept that is referenced that I have no idea what it is or how it works.

Draw me a picture of how to think about everything and how each piece relates to the other pieces. So much of my time is spent wading through your documentation trying to find anything that will help me solve whatever problem I am trying to solve. Once I, finally, have a good mental model of something, then it’s very easy to find what I am looking for in your documentation. However, during the process when I’m trying to learn how everything works while simultaneously trying to implement my client’s changes, I find it almost impossible sometime to find what I need, and the reason is that I don’t have a good mental model of things.

If you could add a section in your documentation that describes the concepts and how they all relate to one another, some illustrations, say, of how a page gets build from all of the various little pieces, it would make your documentation so much more ingestible and understandable from the point of view of someone like me: a developer who knew absolutely nothing about Big Commerce, Stencil, how themes works, etc. etc. It’s been an awful uphill climb, and, after months of trying to get that understanding, I am just beginning to understand how it all fits together and how I can be most valuable to my client.

Can UpdateShipment change the addresses or not?

When I try to generate code from BigCommerce_Orders_API.oas2.json, I get the following error

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
| Error count: 2, Warning count: 11
Errors:
-attribute paths.'/orders/{order_id}/shipments/{shipment_id}'(put).[['unknown']].in is missing
-attribute responses.OrdersCountResponseCollection.description is missing
Warnings:
-attribute paths.'/orders/{order_id}/shipments/{shipment_id}'(put).[['unknown']].in is missing
-attribute responses.OrdersCountResponseCollection.description is missing

    at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:470)
    at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:497)
    at org.openapitools.codegen.cmd.Generate.run(Generate.java:415)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:61)

The missing description is easy enough to fix, but the missing in is interesting. The parameters for that method start off normally: ref to Accept header, ref to Content-Type header, a body with a ref to createupdateordershipment. But then there's another schema, that looks like a createupdateordershipment, but it also contains items, billing_address, and shipping_address properties, unlike the other one. Interestingly, the example for createupdateordershipment includes those three properties, so I don't know what is intended. These two objects look like they should be merged, but someone else should make the call.

App Quick Start guide links to codesandbox.io without listing it in prerequisites

App Quick Start guide links to codesandbox.io and presumes that one is using it without listing it in prerequisites. It's also unclear when the guide is using "sandbox" to mean "codesandbox.io" or the BigCommerce store which is also referred to as a sandbox

https://developer.bigcommerce.com/api-docs/apps/quick-start

After registering the app, enter the app’s credentials and auth callback into your sandbox’s environment variables (codesandbox.io).

Create an Order schema is incorrect

According to this page one should be able to set the shipping_addresses of an order, but the reference for Create an Order has the same schema for the request and response, namely saying the shipping_addresses field is read-only and contains a reference to the API endpoint to read that order's shipping addresses.

how to implement an application made with nexjs in my store within the bigcommerce

how to implement an application made with nexjs in my store within the bigcommerce?

Inconsistent parameters in first OAuth get request

dev-docs/apps-05-oauth.md describes the parameters to the first GET request in two places, and there are inconsistent. I would expect the parameters listed to be identical, but they are different.

Under OAuth summary, step 1:

GET request from BigCommerce to your app (triggered by merchant clicking Install) containing:

• code
• client_id
• client_secret
• scopes

Under Receiving the GET request:

GET /auth?code=qr6h3thvbvag2ffq&scope=store_v2_orders&context=stores/g5cd38 HTTP/1.1

Parameter	Description
code	Temporary code to exchange for a permanent access_token.
scope	List of scopes authorized by the user.
context	The store_hash in the form of stores/{{STORE_HASH}}; required in API requests.

Test param removed from Stencil Start

It looks like stencil start --test was removed in stencil cli commit c39c67b however the docs have not been updated.

Feedback for “Custom Templates”

Looks like placeholder text exists for where the actual examples of mapping looks like should be.
Example 1: text "Populated brand, page, and category keys" (doesn't actually show any example where one would expect)
Example 2, begins with: In addition to mapping a single array to a URL you can also map an array of URLs to each template. This is shown in the following example for the product template: "Map multiple URLs" (quotation marks added for emphasis of where one would expect to see the example shown of actual code)

Feedback for “Custom Templates”

“ After editing your .stencil or config.stencil.json files (if you are using Stencil V3.1 release or later), you must restart the Stencil app to view your changes locally. To restart stencil, type stencil start at a command prompt, and append the appropriate switches for your workflow, for example: stencil start -e -n.”

Looking in the stencil start documentation (https://developer.bigcommerce.com/stencil-docs/installing-stencil-cli/stencil-cli-options-and-commands#stencil-init), I cannot find anything that explains what the -e option to stencil start does.

Installing Stencil CLI no longer requires Rosetta on Apple silicon

https://developer.bigcommerce.com/stencil-docs/installing-stencil-cli/installing-stencil

The instructions on this page for Installing on Mac are out of date, as running Terminal with Rosetta is no longer required with Node 18 on Apple silicon.

Feedback for “Webhook Events”

hash : The payload data JSON encoded then passed through SH1 encryption.

this is written in this doc
https://developer.bigcommerce.com/api-docs/store-management/webhooks/webhook-events#callback-structure

tho when i'm trying to generate hash using app secret
not get generated correctly

please provide more information on how exactly the hash should be generated

“Using Front Matter”: Remove statement that you can't use front matter in custom templates

It's outdated to list templates/pages/custom/ as one of the directories where YAML front matter cannot be used. The sentence "Injecting objects in the front matter of templates/pages/page.html will make the objects available to custom templates." should also be removed because it refers to the same previous restriction.

Test

Page: Feedback
Details: Summary

Test

Page: Praise
Details: Summary

Can we update only a few properties on a product?

Hello -

We would like to update only a select attirbutes via API. Is that possible to do with the new api? If not, when will that be available ?

Thank you!
CJ

Install support for ARM based macs (Apple Silicon)

The install instructions no longer work with ARM-based macs as they try to fetch the wrong node version...

➜  ~ nvm install 12
Downloading https://nodejs.org/dist/v12.19.1/node-v12.19.1-darwin-arm64.tar.gz...
#=#=#
Checksums empty
tar: Error opening archive: Unrecognized archive format
Binary download failed, trying source.
Binary download failed, trying source.
#=#=#
Checksums empty
tar: Error opening archive: Unrecognized archive format
Binary download failed, trying source.
Installing node v1.0 and greater from source is not currently supported

Feedback for “BigCommerce Apps Quick Start”

You're missing some steps in the quick start:

You mention needing to add CLIENT_ID and CLIENT_SECRET, which both have placeholders in the .env.sample file, but the app also requires STORE_HASH and ACCESS_TOKEN to be set.

You need to already have a database prepared, and then run npm db:setup to initialise it before you can run the server locally.