Hey BigCommerce team!

Not sure this if is the right place to request api features. Feel free to redirect me to the appropriate place if needed.

I'm currently developing a BigCommerce app that needs to fetch all variants' metafields from the whole catalog. I was expecting to be able to include them on a product/variant request, but by the looks of it, it's not supported. Then I started looking for a direct metafield endpoint, I can see that a metafield contains a resource_type and resource_id fields, so I imagine they are stored on a different table. But no luck with that either 😞

So, with that said, I guess I need to request this feature to be implemented. Either of the above solutions would do the trick. I can also imagine that this definitely can be useful for many other developers, as this is a developer-specific field.

Thanks in advance!

Looks like there is an issue with the generated URLs as they should be (for example) /api/storefront/cart-summary/ or /remote/v1/cart/add

See screenshot:

In order to improve our productivity at Space 48 we've been using openapi-typescript to generate TypeScript typings for the BigCommerce API endpoints using the specs in this repo.

The major challenge we are facing is that there are a lot of mistakes in your API specs. Specifically, there are fields in the schemas which have the wrong name, wrong type, or are missing altogether.

We are keen to raise PR's on this repo as we find and fix these bugs, but in the past our PR's have been closed without comment or warning[1][2]. This poses a significant challenge to us, as we have to maintain a fork of these API specs with our fixes applied, and then continually rebase our fixes onto the changes being made in this repo. This isn't viable as the number of fixes we make increases.

Are BC willing to accept PR's to fix bugs in these specs? Why were our previous PR's closed without comment -- is there something we need to do differently?

BC are currently suppressing a lot of Spectral errors which highlight inconsistencies between schemas and example payloads. Is there a goal to eliminate these inconsistencies or is doing so considered out of reach?

In the customer_Full model first_name and last_name have min length 1. However we've seen API responses with a length of 0, which then can't be de-serialised. Can you change the limits

    first_name:
      description: The first name of the customer.
      type: string
      minLength: 1
      maxLength: 100
    last_name:
      description: The last name of the customer.
      type: string
      minLength: 1
      maxLength: 100

to

    first_name:
      description: The first name of the customer.
      type: string
      minLength: 0
      maxLength: 100
    last_name:
      description: The last name of the customer.
      type: string
      minLength: 0
      maxLength: 100

NSwag studio gives the following error when attempting to create a C# client.

Newtonsoft.Json.JsonReaderException: Invalid property identifier character: ?. Path 'paths['/orders/payment_actions/refunds'].post.responses.503.examples', line 1, position 18036.

Also, upon inspecting the BigCommerce API docs https://developer.bigcommerce.com/api-reference/store-management/order-transactions/payment-actions/getorderrefunds the responses other than 200 do not show.

The documented response format is an array with keys data and meta like other v3 endpoints.

However, it actually returns an array of productSortOrders. I'm not sure if the endpoint should be updated to be more consistent with other endpoints but in the meantime, it would be good to get the documentation updated.

Thanks.

https://github.com/bigcommerce/api-specs/edit/master/reference/catalog.v3.yml

Can you please fix all the places where the returning value is either an array or an object? If there is one value in the list can it be and array with that one value.

The example on this page has one error in the response with [] but when testing on a site once error on the response gives me an object.

Its not the only place where this happens and it breaks many json seriallizers. The product custom url is also broken.

Documentation:

"errors": [
    {
      "status": 0,
      "title": "string",
      "type": "string",
      "errors": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],

Example Response:

"errors":
{
"status":422,"title":"Please verify if all required fields are present in the request body and are filled with values correctly.","type":"https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors":{"0.name":"A duplicate category with the name: 'SQUARE TOE' was found in the same parent"
}
}

StoreInformation.logo is an object in the spec, but I'm getting an empty array returned, which is breaking searialization.

When I try and import the catalog.v3.yml file into Postman it's throwing an error "Error while importing: format not recognized"

I've been trying to track down what the problem might be, but so far haven't been able to uncover anything.

It is possible currently to create multiple variants with initial product creation request, but that is not documented in the spec and on the website, though it was documented on the website previously.

Documentation for the /catalog/shared-product-options endpoint does not appear to be published in the current version of the API reference.

Hi

We are about to add support for BugCommerce to our SaaS solution. I'm very glad to see this set of OpenAPI specs as it will make that process much easier. A couple of questions/observations.

1. Are these specs officially supported by BigCommerce? They seem actively maintained, but I didn't see any reference to them in the BC documentation?
2. I've only looked at the CatalogV3 API so far, but I notice that swagger.io and spotlight show there are a few errors in the files. Similarly generating client libraries from the spec, throws some errors too. Are you aware of this, or shall I post up some more specific issues?
3. An observation. You've specified that Accept and Content-Type are required headers on most if not all the API endpoints. Whilst this may be technically correct, the impact is that the client library generators such as openapi generator, require these two parameters to be sent into every API call. It's usually very straightforward to get HTTP client to send in default headers like this without having to pass them via the generated API stub functions. Would you consider removing them from the specs?

Regards

Steven Brookes
TideConnects.com

From my testing of the get all brands endpoint, there is more functionality than documented.

You can sort results using the sort param, e.g. sort=name.

You can search by partial name, e.g. name:like=Foo

https://developer.bigcommerce.com/docs/rest-catalog/product-variant-options/values#update-a-product-variant-option-value

is_default is documented with the note:

The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.

I have been able to the swatch option value with the is_default in BC admin and via the API without issue. Does this annotation need removing or correcting?

Using openapi-generator (with --skip-validation) I was able to compile a Python client from these specs for the Catalog V3 API. However it's not usable - every request I try comes back with one error or another, simple operations like getting the catalog summary or a single product fail because of a mismatch between the specs and the actual responses.

Is the intention of this project to enable client code generation or is it simply for the generation of the online documentation? Given that the "official" Python API client is pretty much abandoned and doesn't work with any V3 endpoints, it would be ideal to use this if possible. If we submit issues for the errors we encounter with generated code, will they be addressed?

In get all products, the variant id is missing

image_url looks like it might also be missing

https://github.com/bigcommerce/api-specs/blob/main/reference/webhooks.v3.yml#L3032

        headers:
          type: object
          description: 'Headers used to validate that webhooks are active. You can pass in any number of custom headers to validate webhooks are being returned. '
          nullable: true
          properties:
            custom:
              type: string

Should probably be:

        headers:
          type: object
          description: 'Headers used to validate that webhooks are active. You can pass in any number of custom headers to validate webhooks are being returned. '
          nullable: true
          additionalProperties:
             type: string

Hi everybody and thank you for your work :)

I've noticed that in management API v2/orders there are optional order fields that are present when the store has multiple currencies:

The following additional fields are returned on orders when Multi-Currency is enabled on the store:
store_default_currency_code - the currency code of the store’s default currency.
store_default_to_transactional_exchange_rate - the exchange rate between the store’s default currency and the transactional currency used in the order.

(https://developer.bigcommerce.com/api-reference/store-management/orders)

In orders.v2.oas2.yml these fields are present in response example, but not in the #/components/schemas/order_Resp.
Is there some technical problem or it just was forgotten?

Thank you,
Martin

https://github.com/bigcommerce/api-specs/blob/main/reference/webhooks.v3.yml#L594 It seems like the webhook id, and probably the timestamps should be integers, not numbers?

A question more than anything. :) Thanks for listening.

I know this repo is about generating docs, but I'd also love to generate models/clients. For the past couple of years it's been pretty common for the specs to have (sometimes small) validation errors when using the official OpenAPI generator.

Any thoughts on extending the scope of this project to also be useful for generating models/clients? Ideally, it'd be amazing to validate in CI during PRs, such that the specs on the default branch (currently master) always validate and succeed in generating code.

As a customer of the BigCommerce API, my ideal usage is to 1) read the docs enough to understand the big picture of how the API works, then 2) generate all the code needed to interact with the API. This is much easier than having to read the docs in great enough detail to write my own client.

Thanks for the work you all do to keep these docs up to date! :)

The API reference for Current Customer API incorrectly documents the endpoint as /api/storefront
/customer/current.jwt. It should be /customer/current.jwt.

Catalog_v3.yml does not parse properly in https://editor.swagger.io/ nor via NSwagStudio

According to the docs: https://developer.bigcommerce.com/api-reference/15b810ee7c012-get-all-widget-templates - channel_id should filter the results by the provided channel_id. However, nothing is filtered.

Using the query param "channel_id:in" works.

Not sure if the docs need changing, or whether the API needs amending to work in the way the docs describe.

Currently, the documentation for Creates a Variant Image located at:
https://developer.bigcommerce.com/api-reference/45bef4d261b13-create-a-variant-image
states "Creates a Variant Image"
Instead, it should say "Creates a new Variant Image if none is assigned, or replaces the existing Variant image if one is already assigned. There is no way to delete a variant image via the API."

I tested the above using Postman to confirm.

The specs have multiple structural violations. Code gen tools like NSwagStudio cannot parse the definition properly.

The model for the Inventory API seems to be missing.

https://developer.bigcommerce.com/docs/rest-management/inventory

I would have expected a YML under https://github.com/bigcommerce/api-specs/tree/main/reference

Could this be added?

Hi there,

I believe optionSelections should be detailed in the schema for the Create Cart endpoint of Storefront Cart API.

This is detailed within the Management APIs but seems to have been omitted on Storefront API, there might be a good reason that I am missing (?), but I've opened the issue and will open a pull request for this too.

Hopefully it helps!

Hi

We saw a couple of issues in the V3 catalog specification whcih gave incorrect code generation.

1. Additional type: string on line 18199 productVariant_Full

2. On line 19182 product_Post
   $ref: '#/definitions/productVariant_Post_Product'
   should be
   type: array
   items:
   $ref: '#/definitions/productVariant_Post_Product'

3. On line 20026 product_Full
   $ref: '#/definitions/productVariant_Full'
   should be
   type: array
   items:
   $ref: '#/definitions/productVariant_Full'

Regards

Steve